exec

type Error struct {
	Status   Status
	Msg      string
	ExitCode int
	Signal   int

	// Permanent means the job must not be retried, however the attempt was
	// carried. The worker treats it exactly as it treats an error wrapping
	// dispatch.ErrPermanent.
	Permanent bool

	// Cause is the handler's own error when the attempt ran in this
	// process. It is what errors.Is and errors.As reach through Unwrap.
	Cause error
}

type Executor interface {
	// Name identifies the executor in configuration, logs, and metrics.
	Name() string

	// Level reports the isolation this executor actually provides, which
	// is what Registry.Select matches a Policy against.
	Level() Level

	// Run executes one attempt.
	//
	// The returned error is reserved for failures to launch — the handler
	// never ran. A handler that ran and failed is reported through
	// Result.Status, so the caller can tell a business failure from a
	// dead sandbox without inspecting error text.
	Run(ctx context.Context, req *Request) (*Result, error)

	// Reclaim releases sandboxes this worker leaked across a restart. The
	// pool calls it once at startup, for every registered executor, and a
	// failure is logged rather than fatal.
	//
	// A later phase runs the same sweep on the leader's behalf for workers
	// the cluster has declared dead; that caller does not exist yet.
	Reclaim(ctx context.Context, workerID id.WorkerID) error

	// Close releases the executor's own resources. The engine calls it for
	// every registered executor when it stops, after the pool has finished
	// its in-flight attempts.
	Close() error
}

type InputSlot struct {
	Name string
	Path string
}

type Level int

type OutputFile struct {
	Name        string
	Size        int64
	Hash        string
	ContentType string
}

type Policy struct {
	// Level is the minimum isolation required.
	Level Level

	// GracePeriod is how long the sandbox has to exit after SIGTERM
	// before it is killed.
	GracePeriod time.Duration

	// AllowDowngrade permits running at a weaker level than Level when
	// the deployment cannot provide it. Without it, a deployment that
	// cannot satisfy the policy fails at registration rather than
	// silently running the handler unisolated.
	AllowDowngrade bool

	// Image overrides the container image for out-of-process rungs.
	// Empty means the worker's own image, which is the correct default
	// because the sandbox re-execs the same binary.
	Image string
}

type PolicyOption func(*Policy)

type PriorOutput struct {
	Name string
	Ref  artifact.Ref
}

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

type Request struct {
	JobID   id.JobID
	Name    string
	Payload []byte
	Attempt int

	// Deadline is when the attempt must be killed. Zero means no deadline.
	Deadline time.Time

	// Fingerprint identifies the handler set the caller expects.
	Fingerprint string

	// InputDir holds staged inputs and is read-only to the handler.
	InputDir string
	// OutputDir is where the handler writes artifacts.
	OutputDir string

	Inputs       []InputSlot
	PriorOutputs []PriorOutput

	Policy Policy

	// ResourceLimits is the job's resolved enforcement ceiling
	// (job.Job.ResourceLimits, see job.WithResourceLimits), carried
	// across the execution boundary so a rung that can enforce something
	// has the per-job numbers to enforce it with. A key absent or zero
	// here means the job declared no ceiling for that dimension; it is
	// not this type's business to say what a rung does about that —
	// exec/subprocess.Executor falls back to its own deployment-wide
	// default in that case, but exec itself has no opinion.
	ResourceLimits resource.Set

	// ScopeAppID and ScopeOrgID label the attempt for logs and metrics.
	// They are identifiers, never credentials.
	ScopeAppID string
	ScopeOrgID string

	// Env is passed to out-of-process rungs. It is not the worker's
	// os.Environ() handed through: exec/subprocess.Executor.buildEnv
	// builds the child's environment from this map plus its own
	// configured base, never starting from the worker's full environment.
	// It does still copy a fixed allowlist of PATH, HOME, and TMPDIR from
	// the worker's own environment ahead of this map — HOME in
	// particular is what locates ~/.aws and similar credential paths, so
	// the dedicated uid this rung requires, not environment exclusion
	// alone, is what actually keeps the child from reading them.
	Env map[string]string
}

type Result struct {
	// Status classifies the outcome.
	Status Status

	// HandlerErr is the handler's error string, or a diagnostic for a
	// launch failure. Empty on success.
	HandlerErr string

	// ExitCode is the sandbox process's exit status, where one applies.
	ExitCode int

	// Signal is the signal number that killed the process, or zero.
	// Stored as an int rather than a syscall.Signal so this leaf package
	// stays free of syscall.
	Signal int

	// Usage records what the attempt consumed.
	Usage Usage

	// Outputs lists the artifacts the sandbox claims to have written.
	Outputs []OutputFile

	// Permanent means retrying cannot change the outcome, so the job skips
	// its remaining attempts. This is the wire-visible half of permanence:
	// a rung that ran the handler in another process cannot send back a Go
	// error chain, but it can send back this flag.
	Permanent bool

	// Cause is the handler's own error, kept whole. It exists so an
	// in-process attempt loses nothing: errors.Is and errors.As against a
	// caller's sentinels keep working through the exec layer.
	//
	// It is deliberately not serialised — an error chain does not survive a
	// process boundary — which is why Permanent exists alongside it. A rung
	// that marshals a Result leaves this nil and sets Permanent instead.
	Cause error `json:"-"`
}

type Status string

type Usage struct {
	WallTime    time.Duration
	CPUTime     time.Duration
	PeakRSS     int64
	DiskWritten int64
}