sandbox

type Job struct {
	Image   string            // runner image carrying the toolchain
	Cmd     []string          // command to run in the container
	Env     map[string]string // environment variables
	WorkDir string            // working directory inside the container
	Mounts  []Mount           // trusted, read-only bind mounts into the container

	// InputTar is an OPTIONAL tar archive of files/dirs handed to the workload as
	// a writable source tree, with no path back to the host filesystem. This is
	// the safe way to give untrusted code (e.g. `go test`) something to run on. A
	// `git archive` tarball can be passed straight in.
	//
	// It is injected into an ephemeral named VOLUME mounted at InputDir, not a
	// host bind mount: a trusted prep container creates the volume, chmods it so
	// the non-root run user can write, and the tar is copied in while that prep
	// container is running. The hardened main container then mounts the populated
	// volume; the volume is removed when RunOnce returns. (Copying into the
	// stopped main container instead would land on its rootfs and block the
	// volume from mounting — hence the prep step.)
	//
	// The image must provide a POSIX shell with `chmod` and `sleep` (busybox,
	// alpine, debian, golang, … all qualify). Tar entry paths are relative to
	// InputDir (entry "main.go" -> <InputDir>/main.go). Set WorkDir to InputDir
	// (or a subdir) to run Cmd there.
	InputTar io.Reader
	InputDir string // absolute dir the InputTar is unpacked into; defaults to "/workspace"

	Collect []string // absolute in-container paths to copy out after exit
	Limits  Limits
}

type Limits struct {
	CPUs     float64       // CPU quota, e.g. 2.0; 0 = unlimited
	MemoryMB int64         // RAM cap in MiB; 0 = unlimited
	PIDs     int64         // max processes; 0 = unlimited
	Timeout  time.Duration // hard wall-clock kill; 0 = no timeout
	Network  string        // "none" | "bridge" | named network; empty = DefaultNetwork
}

type Mount struct {
	Source   string // host path
	Target   string // container path
	ReadOnly bool
}

type Result struct {
	ExitCode  int               // container exit status
	Logs      []byte            // combined, de-multiplexed stdout+stderr
	Artifacts map[string][]byte // Collect path -> file bytes (missing paths are omitted)
	TimedOut  bool              // true if the container was killed at Limits.Timeout
}