backend

type ContextPort interface {
	WithContext(context.Context) Port
}

type EngineUnavailableError struct {
	Engine string
	Err    error
}

type IneligibleError struct {
	Reason string
}

type NotVisibleError struct {
	Stack string
}

type Port interface {
	// Preflight proves the backend is reachable and acting as the
	// identity the policy expects, before a run does any inventory work.
	Preflight() error
	// Observe reads the stack's current state through the backend.
	Observe(stack config.StackPolicy) (StackState, error)
	// RunningDigests re-reads only which digests are running, for the
	// repeated checks verification makes.
	RunningDigests(state StackState) (map[string]string, error)
	// Deploy redeploys the stack with a new Compose document. repull
	// asks the engine to re-pull mutable tags; backends that always pin
	// digests refuse it.
	Deploy(state StackState, compose string, repull bool) error
	// ServicesRunning reports whether every configured service of the
	// stack is running (and healthy where the engine tracks health),
	// with a human-readable detail when it is not. It is the engine-level
	// half of verification; the functional health check is the other.
	ServicesRunning(state StackState) (bool, string, error)
}

type StackState struct {
	Backend domain.Backend
	// Stack is the policy-declared name, the identity used everywhere.
	Stack string
	// Compose is the deployed Compose document as text — the bytes an
	// apply rewrites and a rollback restores.
	Compose string
	// Fingerprint covers everything an apply depends on staying still.
	// Any change between planning and applying is drift.
	Fingerprint string
	// Services are the resolved service names, sorted.
	Services []string
	// ServiceImages is each service's image reference with variable
	// interpolation applied — what the engine will actually run.
	ServiceImages map[string]string
	// DeclaredImages is each service's image reference as literally
	// written in the Compose document. It differs from ServiceImages
	// only for interpolated lines, which cannot be pinned.
	DeclaredImages map[string]string
	// RunningDigests maps service name to the digest currently running.
	// Nil when the backend cannot prove running digests and only the
	// stack-level image status is available.
	RunningDigests map[string]string
	// ImageStatus is the backend's own "updated"/"outdated" verdict, set
	// only when RunningDigests is nil.
	ImageStatus string
	// GitBacked marks a stack deployed from Git, which is never mutated
	// in place — changes go through a Proposal.
	GitBacked bool
	// Handle carries backend-private identity (a Portainer stack, a
	// compose file and project) back into Deploy.
	Handle any
}