passage

type ConfigChecker interface {
	CheckConfig(raw json.RawMessage) error
}

type Engine struct {
	Registry *Registry
	// Now is the clock, injectable for tests.
	Now func() time.Time
}

type Outcome struct {
	// Status is the Passage's updated status. The caller persists it.
	Status v1alpha1.PassageStatus
	// RequeueAfter is how long to wait before calling Advance again. Zero means
	// the Passage is finished.
	RequeueAfter time.Duration
	// Watch accumulates the health checks emitted by steps, for the Gate to
	// adopt once the Passage succeeds.
	Watch []v1alpha1.HealthCheck
}

type Reconciler struct {
	client.Client
	Engine   *Engine
	Recorder events.EventRecorder
	// WorkRoot is the base directory for Passage scratch space. Empty means a
	// directory under the system temp dir.
	WorkRoot string
	// Now is the clock, injectable for tests.
	Now func() time.Time
	// FidesServer is the controller's --fides-server, used to record a finished
	// crossing when a Gate does not name one of its own.
	FidesServer string
	// DialFides is injectable so tests can point at a fake Fides. Nil is the
	// real client.
	DialFides func(fides.Config) (*fides.Client, error)
}

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

type Runner interface {
	// Name is the value used in `steps[].uses`.
	Name() string
	// Run performs one invocation. It must return promptly: to wait, return
	// StepRunning with a RetryAfter rather than sleeping.
	Run(ctx context.Context, sc *StepContext) (StepResult, error)
}

type StepContext struct {
	// Namespace is where the Gate and Bundle live.
	Namespace string
	// Gate being crossed.
	Gate string
	// Passage performing the crossing.
	Passage string
	// Bundle being moved. Steps read artifact versions from here.
	Bundle *v1alpha1.Bundle
	// Actor initiated the Passage. ActorController when nobody did.
	Actor string
	// WorkDir is a scratch directory shared by every step in this Passage —
	// where one step clones a repo and a later one commits it.
	WorkDir string
	// Config is this step's `with:` block.
	Config json.RawMessage
	// Outputs holds prior steps' outputs, keyed by their `as:` alias.
	Outputs map[string]map[string]any
	// Attempt is how many times this step has already run, starting at 0.
	Attempt int32
	// Failed reports that an earlier step has already failed the Passage.
	//
	// A step only sees this if it asked to run anyway (`if: failed` or
	// `if: always`) — otherwise it is skipped and never invoked. It is here so
	// a step reporting the outcome can report the real one: the engine knows,
	// and making the user restate it in configuration would be a second place
	// for the truth to live (D46).
	Failed bool
	// Traceparent is the W3C trace context for this crossing, or empty when
	// tracing is off. Steps that write something durable should carry it, so a
	// promotion can be correlated end to end (D42).
	Traceparent string
	// StartedAt is when the Passage began.
	//
	// Steps that produce content should derive timestamps from this rather than
	// the wall clock, so re-running a Passage yields byte-identical output. A
	// commit stamped with time.Now() gets a new SHA on every attempt, which
	// turns a harmless retry into a second commit on the branch.
	StartedAt time.Time
}

type StepError struct {
	// Reason is a stable, machine-readable code in PascalCase, following the
	// convention Kubernetes uses for condition reasons — GitAuthFailed,
	// FluxStalled, InvalidConfig. Stable is the operative word: it is a
	// contract, so renaming one breaks whatever was matching on it.
	//
	// Deliberately not a closed enum. Each step names its own failures; a
	// central registry would be a bottleneck and a merge conflict, and steps
	// live in different packages.
	Reason string
	// Terminal marks a failure not worth retrying — bad configuration, a
	// missing reference, anything that will fail identically next time.
	Terminal bool
	Err      error
}

type StepProblem struct {
	// Index is the step's position, which is how an author finds it: steps have
	// no required name, so "step 3" is often the only way to point at one.
	Index int
	Uses  string
	Err   error
}

type StepResult struct {
	// Phase is the outcome. StepRunning means "call me again".
	Phase v1alpha1.StepPhase
	// Message explains the phase, and is shown in the UI and CLI while waiting.
	Message string
	// Output is exposed to later steps under this step's alias.
	Output map[string]any
	// Watch are health checks this step hands to the Gate, so the Gate keeps
	// monitoring what the step waited for. Without this a Gate goes blind the
	// moment its Passage finishes.
	Watch []v1alpha1.HealthCheck
	// Evidence is the compliance record this step produced or consulted, copied
	// onto the Passage's status.
	//
	// Carried here rather than dug out of Output by the controller, for the same
	// reason as Watch: a step knows what it recorded, and a controller matching
	// on well-known output keys would break the moment a step chose a different
	// name for them.
	Evidence *v1alpha1.EvidenceRef
	// RetryAfter suggests how long to wait before the next invocation.
	RetryAfter time.Duration
}