// Package host owns the application-layer lifecycle of shared runtime
// dependencies. It declares a narrow Component port and a Status record so
// the bootstrap adapter can wire concrete providers without this package
// touching them directly.
//
// Start launches components in declared order and cancels any already
// started component on the first failure. Stop shuts components down in
// reverse order and preserves every individual error. Repeated Stop calls
// are safe and return nil once the host has fully stopped.
package host

import "context"

// Component is the narrow application-facing port for one runtime
// dependency. Start must return quickly when the dependency is ready; if
// readiness is inherently slow, Start should block on ctx and report
// cancellation. Stop must drain and release every resource the dependency
// acquired during Start.
type Component interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

// Status reports the live state of a Host without exposing internal
// bookkeeping. It is a value type so callers can snapshot it cheaply.
type Status struct {
	// Started lists component names that have successfully completed Start.
	Started []string
	// Failed records the name of the component whose Start returned the
	// error that stopped the forward launch. Empty when no failure
	// occurred.
	Failed string
	// LaunchErr is the first non-nil error returned during Start. It is
	// preserved even after Stop finishes so callers can distinguish
	// "never started" from "started then stopped".
	LaunchErr error
	// StopErr is the combined error from Stop. Empty when Stop has not
	// been called or returned nil.
	StopErr error
	// Stopped is true after Stop has run to completion, regardless of
	// whether Stop itself returned an error.
	Stopped bool
}