service

type BuildContext struct {
	// Identity identifies the service and selected process role.
	Identity ProcessIdentity
	// Logger is the optional caller-owned logger selected by the definition.
	Logger *slog.Logger
	// Correlation creates identifiers for platform-managed work boundaries.
	Correlation *correlation.Factory
}

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

type CommandKind uint8

type CommandSpec[C any] struct {
	// Name is the lowercase kebab-case command token.
	Name string
	// Summary is the one-line help description.
	Summary string
	// Kind determines whether the command is long-running or one-shot.
	Kind CommandKind
	// Options declares bounded command-specific CLI input. Configuration
	// loaders retain the immutable raw invocation for application validation.
	Options []cli.OptionDefinition
	// Load decodes and validates command-specific configuration.
	Load func(context.Context, Invocation) (C, error)
	// Build constructs the owned runtime plan from typed configuration.
	Build func(context.Context, BuildContext, C) (Plan, error)
}

type Commands struct {
	// Serve registers the standard serve role.
	Serve Command
	// Worker registers the standard worker role.
	Worker Command
	// Schedule registers the standard schedule role.
	Schedule Command
	// Migrate registers the standard migrate role.
	Migrate Command
	// Custom contains explicitly named application commands.
	Custom []Command
}

type Component struct {
	// Name is the unique diagnostic name used in typed lifecycle errors.
	Name string
	// CloseAdmission synchronously and idempotently stops new work from entering
	// the component. It runs once when service drain begins, before service-
	// initiated cancellation, and must return promptly. A parent context may
	// already be canceled. Nil is a valid no-op.
	CloseAdmission func() error
	// Start acquires the component resources and transfers ownership only when
	// it returns nil. It must honor context cancellation.
	Start func(context.Context) error
	// Stop releases resources after a successful Start and must honor context
	// cancellation. Nil is a valid no-op.
	Stop func(context.Context) error
}

type ComponentError struct {
	// Component is the configured component or supervised task name.
	Component string
	// Operation is the failed lifecycle operation.
	Operation string
	// Err is the original failure and remains available through errors.Is and
	// errors.As.
	Err error
}

type Config struct {
	// Components start in listed order and stop in reverse successful order.
	Components []Component
	// StartupTimeout bounds context-aware component acquisition. Zero uses the
	// documented default.
	StartupTimeout time.Duration
	// RollbackTimeout bounds the caller's wait after startup failure. Zero uses
	// the documented default.
	RollbackTimeout time.Duration
	// MaxTasks caps concurrently active supervised tasks. Zero uses the
	// documented default.
	MaxTasks int
}

type ConfigError struct {
	// Field identifies the rejected configuration path.
	Field string
	// Reason describes why Field was rejected without exposing secret values.
	Reason string
}

type ConfigurationError struct {
	// Command identifies the selected command.
	Command string
	// Err retains the application configuration cause.
	Err error
}

type ConstructionError struct {
	// Command identifies the selected command or runtime boundary.
	Command string
	// Err retains the application construction cause.
	Err error
}

type Definition struct {
	// Identity identifies the deployable service.
	Identity Identity
	// Commands declares every supported process role.
	Commands Commands
	// Logger is caller owned. Nil keeps logging disabled.
	Logger *slog.Logger
	// Observer receives bounded lifecycle, task, probe, and maintenance events.
	Observer RuntimeObserver
	// CorrelationDisclosure controls correlation values included in platform
	// logs. The zero value redacts identifiers.
	CorrelationDisclosure correlation.DisclosurePolicy
	// Correlation is caller owned. Nil selects the correlation default.
	Correlation *correlation.Factory
	// TracePropagation optionally extracts caller-owned trace context after
	// correlation.
	TracePropagation serverhttp.Middleware
	// Management configures the platform-owned operational listener.
	Management Management
	// Maintenance optionally enables shared operational maintenance state,
	// built-in down/up/status commands, readiness withdrawal, and HTTP admission.
	Maintenance Maintenance
}

type DefinitionError struct {
	// Field identifies the rejected definition path.
	Field string
	// Reason safely describes the rejected contract.
	Reason string
}

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

type HTTP struct {
	// Address is bound by the platform. Exactly one of Address and Listener is
	// required.
	Address string
	// Listener transfers ownership after successful plan validation.
	Listener net.Listener
	// Handler owns application routing and protocol behavior.
	Handler http.Handler
	// Options explicitly customize the serverhttp runtime.
	Options []serverhttp.Option
	// TrustCorrelation authenticates an immediate peer before inbound
	// correlation metadata is preserved.
	TrustCorrelation func(*http.Request) bool
	// RejectInvalidCorrelation returns HTTP 400 instead of replacing malformed
	// metadata.
	RejectInvalidCorrelation bool
}

type Identity struct {
	// Name is the stable lowercase service name.
	Name string
	// Version is the semantic build version, or empty when unavailable.
	Version string
	// Commit is the hexadecimal source revision, or empty when unavailable.
	Commit string
	// BuildTime is an RFC3339 build timestamp, or empty when unavailable.
	BuildTime string
	// GoVersion is the Go toolchain version, or empty when unavailable.
	GoVersion string
	// Environment identifies the deployment environment without becoming a
	// metric label.
	Environment string
	// Instance identifies the process instance without becoming a metric label.
	Instance string
}

type Invocation struct {
	// Args is the tokenized argument list without the process name.
	Args []string
	// Environment is the immutable process-environment snapshot.
	Environment []string
	// Stdout receives help, version, and successful command output.
	Stdout io.Writer
	// Stderr receives one safe terminal diagnostic.
	Stderr io.Writer
	// Signals supplies deterministic cancellation events. Nil follows only the
	// parent context.
	Signals <-chan os.Signal
	// contains filtered or unexported fields
}

type Maintenance struct {
	// Store supplies runtime snapshots and the built-in command operations.
	Store MaintenanceStore
	// RefreshInterval controls how often a running process refreshes Store.
	RefreshInterval time.Duration
	// OperationTimeout bounds store operations. Zero selects one second.
	OperationTimeout time.Duration
	// Response optionally renders a caller-owned maintenance body. The platform
	// writes status 503 and maintenance headers before invoking it.
	Response http.Handler
}

type MaintenanceError struct {
	// Operation is the bounded operation name.
	Operation string
	// Err preserves the cause without formatting it.
	Err error
}

type MaintenanceSource interface {
	// LoadMaintenance returns the latest complete snapshot.
	LoadMaintenance(context.Context) (MaintenanceState, error)
}

type MaintenanceState struct {
	// Enabled controls business admission and readiness.
	Enabled bool
	// Since records when maintenance was enabled.
	Since time.Time
	// RetryAfter becomes the Retry-After response header.
	RetryAfter time.Duration
	// Refresh becomes the Refresh response header.
	Refresh time.Duration
	// Redirect is an optional absolute-path redirect.
	Redirect string
	// Secret is an optional URL-safe bypass token. It is never rendered by
	// status output, errors, logs, or runtime events.
	Secret string
}

type MaintenanceStore interface {
	MaintenanceSource
	// StoreMaintenance atomically publishes an enabled snapshot.
	StoreMaintenance(context.Context, MaintenanceState) error
	// ClearMaintenance atomically disables maintenance.
	ClearMaintenance(context.Context) error
}

type MaintenanceStoreOperations struct {
	// Load reads the latest complete caller-owned snapshot.
	Load func(context.Context) (MaintenanceState, error)
	// Store atomically publishes an enabled caller-owned snapshot.
	Store func(context.Context, MaintenanceState) error
	// Clear atomically disables the caller-owned snapshot.
	Clear func(context.Context) error
}

type Management struct {
	// Address is bound by the platform. Empty with no Listener selects
	// 127.0.0.1:8081.
	Address string
	// Listener transfers ownership after successful plan validation.
	Listener net.Listener
	// Details enables bounded check names and binary statuses.
	Details bool
	// TrustCorrelation authenticates an immediate peer before inbound
	// correlation metadata is preserved.
	TrustCorrelation func(*http.Request) bool
	// RejectInvalidCorrelation returns HTTP 400 instead of replacing malformed
	// metadata.
	RejectInvalidCorrelation bool
}

type PanicError struct {
	// Component is the component or supervised task that panicked.
	Component string
	// Operation is the lifecycle operation that panicked.
	Operation string
	// Value is the recovered panic value. Error deliberately does not format it.
	Value any
}

type Plan struct {
	// Components start in declaration order and stop in reverse order.
	Components []Component
	// Tasks are finite one-shot work or supervised long-running work.
	Tasks []Task
	// HTTP optionally declares one business HTTP listener for a long-running
	// command.
	HTTP *HTTP
	// Readiness contains only dependencies required to accept new work.
	Readiness []ReadinessCheck
	// Management explicitly enables probes for a one-shot command. It is
	// ignored for long-running commands, which always expose probes.
	Management bool
	// ManagementConfig overrides the definition-level management listener for
	// the selected plan. The platform snapshots the pointed-to value.
	ManagementConfig *Management
}

type ProcessIdentity struct {
	Identity
	// Role is the selected command name.
	Role string
}

type ReadinessCheck struct {
	// Name is the unique secret-safe dependency name.
	Name string
	// Run evaluates whether the dependency can accept new work.
	Run func(context.Context) error
}

type RunConfig struct {
	// Signals is the set that initiates shutdown. Empty uses platform defaults.
	Signals []os.Signal
	// ShutdownTimeout bounds cleanup after cancellation. Zero uses the
	// documented default.
	ShutdownTimeout time.Duration
}

type RuntimeEvent struct {
	// Kind identifies the platform boundary.
	Kind RuntimeEventKind
	// Result is the bounded outcome classification.
	Result RuntimeEventResult
	// Identity identifies the service process and selected role.
	Identity ProcessIdentity
	// Boundary names the validated component, task, probe, or store boundary.
	Boundary string
	// Duration is the measured operation duration when applicable.
	Duration time.Duration
	// Transition reports an availability or lifecycle state transition.
	Transition bool
	// Method is a bounded HTTP method for request events only.
	Method string
	// Status is an HTTP response status for request events only.
	Status int
	// At is the event publication time.
	At time.Time
}

type RuntimeEventKind string

type RuntimeEventResult string

type RuntimeObserver interface {
	// ObserveRuntime receives one completed bounded platform observation.
	ObserveRuntime(context.Context, RuntimeEvent)
}

type RuntimeObserverFunc func(context.Context, RuntimeEvent)

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

type ShutdownError struct {
	// Failures contains component and supervised-task failures in observation
	// order.
	Failures []error
}

type ShutdownTimeoutError struct {
	// Err retains the deadline cause.
	Err error
}

type SignalError struct {
	// Signal is the process signal that initiated cancellation.
	Signal os.Signal
}

type StartupError struct {
	// Component identifies the component whose startup failed.
	Component string
	// Err is the startup failure.
	Err error
	// Rollback contains every retained reverse-cleanup failure.
	Rollback []error
}

type State uint8

type StateError struct {
	// Operation is the rejected lifecycle operation.
	Operation string
	// State is the lifecycle state in which Operation was rejected.
	State State
}

type Task struct {
	// Name is the unique secret-safe diagnostic name.
	Name string
	// Run executes owned work and must honor context cancellation.
	Run func(context.Context) error
}