proc

type AttachValue struct {
	// Cgroup is a cgroup v2 path as /proc/<pid>/cgroup names it —
	// "/system.slice/web.service" —: the process must be in it or below it. Empty
	// checks no cgroup.
	Cgroup string
	// UIDs are the users the process may run as: its real and its effective uid
	// must both be one of them. Empty checks no user.
	UIDs []int
}

type CapabilitiesValue struct {
	// Bounding is the bounding set the child keeps (systemd
	// CapabilityBoundingSet=): every capability the kernel knows outside it is
	// dropped with PR_CAPBSET_DROP, which needs CAP_SETPCAP — as uid 0 in a user
	// namespace has. The zero value drops them all.
	Bounding uint64
	// Ambient is raised in the child's ambient set (systemd
	// AmbientCapabilities=), so a program that is not root keeps them across
	// execve; its inheritable set becomes this one. It must lie within Bounding.
	Ambient uint64
	// SecureBits, when non-zero, is set with PR_SET_SECUREBITS (systemd
	// SecureBits=), its bits those of linux/securebits.h.
	SecureBits uint32
}

type ContextWaiter interface {
	// WaitContext waits like Wait until the process exits or ctx is done. When
	// ctx ends first it returns ctx's error and the child keeps running; a later
	// Wait or WaitContext still reports the real exit.
	WaitContext(ctx context.Context) (ExitValue, error)
}

type Controller uint8

type DescriptorsValue struct {
	// Files are the descriptors the datagram carried (SCM_RIGHTS): with
	// FDSTORE=1 the ones to store, with BARRIER=1 the barrier, which the caller
	// closes once every earlier datagram is processed.
	Files []*os.File
	// MainPIDFD is the pidfd a MAINPIDFD=1 datagram carried: its process is the
	// new main process, and MainPID its PID; nil when none.
	MainPIDFD *os.File
	// SenderPIDFD is a pidfd on the sending process (SCM_PIDFD, Linux 6.5 and
	// later): the sender itself, beyond the reach of a PID reuse; nil where the
	// kernel attaches none.
	SenderPIDFD *os.File
}

type ExitValue struct {
	// Code is the exit status (0–255) when the process exited normally; it is -1
	// when the process was terminated by a signal.
	Code int
	// Signal is the signal that terminated the process, or the zero Signal when
	// it exited normally.
	Signal Signal
	// Signaled reports whether the process was terminated by a signal rather
	// than exiting on its own.
	Signaled bool
	// UserTime is the CPU time spent in user mode.
	UserTime time.Duration
	// SystemTime is the CPU time spent in kernel mode on the process's behalf.
	SystemTime time.Duration
	// MaxRSS is the peak resident set size in KiB on every platform, read from
	// wait4's rusage: darwin and ios report bytes, which are converted to KiB
	// rounding up; Linux and the BSDs report KiB, passed through. It is 0 when
	// the platform does not supply it (illumos, Solaris and Windows).
	MaxRSS int64
	// CoreDumped reports whether the signalled death left a core image
	// (WaitStatus.CoreDump). It is false for a normal exit, and wherever the
	// platform cannot say (Windows).
	CoreDumped bool
	// Usage is the rest of wait4's resource accounting — page faults, block I/O
	// and context switches — read from the same rusage as UserTime and MaxRSS.
	// It is nil where the platform does not supply it (illumos, Solaris and
	// Windows).
	Usage *UsageValue
}

type FDPolicy uint8

type Group interface {
	// SetMemoryMax writes memory.max (systemd MemoryMax=); a negative value
	// means "max" (no limit).
	SetMemoryMax(bytes int64) error
	// SetCPUMax writes cpu.max as "quota period" (systemd CPUQuota=); a negative
	// quota means "max".
	SetCPUMax(quota, period int64) error
	// SetPidsMax writes pids.max (systemd TasksMax=); a negative value means
	// "max".
	SetPidsMax(n int64) error
	// SetIOMax writes one io.max line verbatim (systemd IO*Max=), e.g.
	// "8:0 rbps=1048576".
	SetIOMax(spec string) error
	// Add moves the process pid into this group by writing cgroup.procs.
	Add(pid int) error
	// Kill atomically SIGKILLs every process in the group by writing "1" to
	// cgroup.kill (systemd KillMode=control-group; kernel >= 5.14). Unlike a
	// process-group kill, nothing escapes — a member that called setsid is still
	// in the control group. Returns UnsupportedPlatform when cgroup.kill is absent
	// (older kernels), so callers can fall back to SignalGroup.
	//
	// Kill a group nothing will be spawned into again: on Linux (measured on
	// 6.12), after one cgroup.kill — an empty group's too — every child later
	// cloned into the group (Spec.CgroupPath, CLONE_INTO_CGROUP) is SIGKILLed at
	// its fork, while a process moved in by Add is not. To empty a group that
	// will be reused, signal its members instead (GroupSignaler's Signal).
	Kill() error
	// Freeze quiesces the whole group by writing "1" to cgroup.freeze (kernel
	// >= 5.2), stopping every member so a consistent signal sweep or snapshot can
	// run. Returns UnsupportedPlatform when cgroup.freeze is absent. Idempotent.
	Freeze() error
	// Thaw resumes a frozen group by writing "0" to cgroup.freeze. Returns
	// UnsupportedPlatform when cgroup.freeze is absent. Idempotent.
	Thaw() error
	// Delete removes the (empty) control group; callers move processes out first.
	Delete() error
}

type GroupEventsValue struct {
	// MemoryEvents counts what the group's memory limits did — memory.events,
	// zero where the memory controller is not enabled for the group.
	MemoryEvents MemoryEventsValue
	// Populated reports that the group or a group beneath it holds a live
	// process (cgroup.events "populated").
	Populated bool
	// Frozen reports that the group is frozen (cgroup.events "frozen").
	Frozen bool
}

type GroupReader interface {
	// Stat reads the group's counters: CPU time and throttling, memory now, at
	// its peak and the events of its limits, the pid count, the I/O per device.
	// It returns CgroupReadFailed when the group's own files cannot be read —
	// the group was deleted.
	Stat() (GroupStatValue, error)
	// Members lists the pids of the group's processes and of the groups
	// beneath it — the cgroup.procs of the subtree, the tracked set, the
	// job's process list — in no promised order: a process a delegated
	// service moved into a group of its own is still the group's.
	Members() ([]int, error)
}

type GroupSignaler interface {
	// Signal sends sig to every process of the group and of the groups beneath
	// it but the caller's own, reading cgroup.procs again until a pass finds no
	// process it has not signalled, at most 64 passes. A process gone before the
	// signal reached it is not an error; any other refusal is SignalFailed.
	Signal(sig Signal) error
	// Contains reports whether pid is a process of the group or of a group
	// beneath it. CgroupReadFailed when the group's cgroup.procs cannot be read.
	Contains(pid int) (bool, error)
}

type GroupStatValue struct {
	// CPUUsage is the CPU time the group's tasks used, user and system.
	CPUUsage time.Duration
	// CPUUser is the user-mode share of CPUUsage.
	CPUUser time.Duration
	// CPUSystem is the kernel-mode share of CPUUsage.
	CPUSystem time.Duration
	// ThrottledTime is how long cpu.max held the group's tasks back.
	ThrottledTime time.Duration
	// NrThrottled is how many periods cpu.max throttled the group in.
	NrThrottled int64
	// MemoryCurrent is the memory the group holds now, in bytes.
	MemoryCurrent int64
	// MemoryPeak is the most memory the group held, in bytes (Linux 5.19's
	// memory.peak; Windows' peak job memory).
	MemoryPeak int64
	// MemoryEvents counts what the group's memory limits did.
	MemoryEvents MemoryEventsValue
	// PidsCurrent is how many tasks the group holds now.
	PidsCurrent int64
	// IO is the I/O the group did, one entry per device.
	IO []IOStatValue
	// Partial reports that at least one counter could not be read and is zero.
	Partial bool
}

type GroupTree interface {
	// Path is the group's directory: the CgroupPath a Spec spawns a child straight into.
	Path() string
	// EnableControllers writes ctrls to the group's cgroup.subtree_control, so
	// the groups beneath it get their interface files. A controller the group's
	// cgroup.controllers does not list is CgroupControllerAbsent, and a
	// malformed name InvalidSpec, before anything is written; while the group
	// itself holds a process the kernel refuses with EBUSY, CgroupWriteFailed
	// (cgroup v2's no-internal-process rule).
	EnableControllers(ctrls ...Controller) error
	// Delegate hands the group to the user uid and the group gid (systemd
	// Delegate=yes): it changes the owner of the directory and of the files the
	// kernel lists in /sys/kernel/cgroup/delegate — cgroup.procs,
	// cgroup.threads and cgroup.subtree_control where that list is absent — so
	// that user may create groups beneath it, move its processes and enable
	// controllers. -1 keeps an owner unchanged. A file the group lacks is
	// skipped; a refused change is CgroupWriteFailed.
	Delegate(uid, gid int) error
	// DeleteTree removes the group and every group beneath it, deepest first:
	// what a delegated unit made under its group goes with it, as systemd
	// cleans a Delegate=yes unit up. A group still holding a process stops it
	// with CgroupDeleteFailed naming that group — Kill, and wait for Watch to
	// say the group is empty, first. A link is never followed.
	DeleteTree() error
}

type GroupTuner interface {
	// SetMemoryMin writes memory.min (systemd MemoryMin=), the memory the group
	// keeps whatever the pressure; a negative value writes "max".
	SetMemoryMin(bytes int64) error
	// SetMemoryLow writes memory.low (systemd MemoryLow=), the memory reclaimed
	// from the group only when nothing else can be; a negative value writes
	// "max".
	SetMemoryLow(bytes int64) error
	// SetMemoryHigh writes memory.high (systemd MemoryHigh=), the throttle
	// above which the group's allocations are slowed and reclaimed; a negative
	// value writes "max".
	SetMemoryHigh(bytes int64) error
	// SetMemorySwapMax writes memory.swap.max (systemd MemorySwapMax=); a
	// negative value writes "max".
	SetMemorySwapMax(bytes int64) error
	// SetMemoryZswapMax writes memory.zswap.max (systemd MemoryZSwapMax=); a
	// negative value writes "max".
	SetMemoryZswapMax(bytes int64) error
	// SetMemoryZswapWriteback writes memory.zswap.writeback (systemd
	// MemoryZSwapWriteback=, Linux 6.8): false keeps the group's compressed
	// pages from being written back to swap.
	SetMemoryZswapWriteback(enabled bool) error
	// SetMemoryOOMGroup writes memory.oom.group: true makes the OOM killer end
	// the whole group rather than one task of it (systemd OOMPolicy=kill).
	SetMemoryOOMGroup(enabled bool) error
	// SetCPUWeight writes cpu.weight (systemd CPUWeight=), the group's share of
	// CPU against its siblings, 1 to 10000 (100 by default).
	SetCPUWeight(weight int64) error
	// SetCPUMaxBurst writes cpu.max.burst, the CPU time the group may borrow
	// above cpu.max's quota in a period, in microseconds; a negative burst is
	// InvalidSpec.
	SetCPUMaxBurst(burst time.Duration) error
	// SetCPUSetCPUs writes cpuset.cpus (systemd AllowedCPUs=) in the kernel's
	// list form, "0-3,8"; an empty list writes "", the parent's CPUs. A
	// negative CPU is InvalidSpec.
	SetCPUSetCPUs(cpus []int) error
	// SetCPUSetMems writes cpuset.mems (systemd AllowedMemoryNodes=) in the
	// list form SetCPUSetCPUs writes.
	SetCPUSetMems(nodes []int) error
	// SetIOWeight writes io.weight's default (systemd IOWeight=), the group's
	// share of I/O against its siblings, 1 to 10000 (100 by default).
	SetIOWeight(weight int64) error
	// SetIOLatency writes the io.latency line of the device major:minor
	// (systemd IODeviceLatencyTargetSec=): the latency the group's I/O is
	// protected to, in microseconds; zero removes it, and a negative target is
	// InvalidSpec.
	SetIOLatency(major, minor uint32, target time.Duration) error
}

type GroupWatcher interface {
	// Watch returns a channel holding the group's state first, then its state
	// after each change the kernel announces: populated, frozen, the memory
	// events. The channel holds one value, and a burst coalesces into the
	// latest — published even when the burst left the state as it was, so a
	// reader that read the group meanwhile learns it changed back: the watch
	// never blocks on its reader. It is closed when ctx ends, and when the
	// group is gone, after a last value holding no process; a reader whose ctx
	// is not done reads the close as the group's removal. CgroupReadFailed
	// when the group's cgroup.events cannot be watched or read.
	Watch(ctx context.Context) (<-chan GroupEventsValue, error)
}

type IDMapValue struct {
	// Inside is the first id in the namespace.
	Inside uint32
	// Outside is the id Inside maps to in the supervisor's namespace.
	Outside uint32
	// Size is the number of ids mapped; it must be at least 1.
	Size uint32
}

type IOClass int

type IOStatValue struct {
	// Major is the device's major number.
	Major uint32
	// Minor is the device's minor number.
	Minor uint32
	// RBytes is the bytes read.
	RBytes uint64
	// WBytes is the bytes written.
	WBytes uint64
	// RIOs is the read operations.
	RIOs uint64
	// WIOs is the write operations.
	WIOs uint64
}

type JobLimiter interface {
	// SetJobMemoryLimit caps the memory committed by every process of the job
	// together (JOB_OBJECT_LIMIT_JOB_MEMORY); a negative value removes the cap.
	// CgroupWriteFailed when the job refuses it.
	SetJobMemoryLimit(bytes int64) error
}

type LandlockAccess uint64

type LandlockRuleValue struct {
	// Path is the absolute file or directory the rule covers, opened by the
	// child after its mounts and its pivot.
	Path string
	// Access is the set of rights granted beneath Path; it must lie within
	// LandlockValue.Handled.
	Access LandlockAccess
}

type LandlockValue struct {
	// Handled is the set of rights restricted; it must not be empty.
	Handled LandlockAccess
	// Rules grant rights beneath paths.
	Rules []LandlockRuleValue
	// BestEffort is the set of rights dropped rather than refused when the
	// kernel's ABI lacks them.
	BestEffort LandlockAccess
}

type LimitValue struct {
	// Soft is the enforced limit; it must not exceed Hard.
	Soft uint64
	// Hard is the ceiling for Soft; raising it typically requires privilege.
	Hard uint64
}

type Listener interface {
	// Recv blocks until the next datagram arrives and returns it parsed, with the
	// sender PID verified by the kernel. It returns a typed error on a malformed
	// datagram or once the listener is closed.
	Recv() (NotificationValue, error)
	// Close releases the socket and unblocks any in-flight Recv.
	Close() error
}

type MemoryBound uint8

type MemoryEventsValue struct {
	// Low counts reclaims under memory.low's protection.
	Low int64
	// High counts the times the group was throttled above memory.high.
	High int64
	// Max counts the times the group hit memory.max.
	Max int64
	// OOM counts the times the group ran out of memory.
	OOM int64
	// OOMKill counts the tasks the OOM killer ended in the group.
	OOMKill int64
}

type MemoryLimitValue struct {
	// Allowance is the tightest cgroup memory cap governing this process, in
	// bytes, or zero when none was read.
	Allowance int64
	// Limit is the Go soft memory limit derived from Allowance, in bytes, or
	// zero when no limit was applied.
	Limit int64
	// Source names what decided the outcome.
	Source MemorySource
	// Bound names the file that set Allowance — memory.high or the hard cap —
	// on every outcome that carries an Allowance, and is zero otherwise.
	Bound MemoryBound
}

type MemorySource uint8

type MountKind uint8

type MountValue struct {
	// Kind is what is mounted.
	Kind MountKind
	// Source is the directory or file a MountBind binds; empty for every other
	// kind.
	Source string
	// Target is the absolute path mounted on; it must exist.
	Target string
	// ReadOnly makes a MountBind or a MountTmpfs read-only, recursively (a
	// MountReadOnly always is).
	ReadOnly bool
}

type Namespace uint32

type NotificationValue struct {
	// State is the raw NAME=value field set from the datagram (READY, STATUS,
	// MAINPID, WATCHDOG, RELOADING, STOPPING, …), preserved verbatim.
	State map[string]string
	// Status is the free-text STATUS= line, empty when absent.
	Status string
	// MainPID is the PID advertised by MAINPID=, or 0 when absent.
	MainPID int
	// SenderPID is the sending process's PID as verified by the kernel via
	// SO_PASSCRED, not a value the sender can forge; 0 when credentials were
	// unavailable.
	SenderPID int
	// SenderUID is the sending process's user, as verified by the kernel with
	// SenderPID; it means nothing when SenderPID is 0.
	SenderUID int
	// SenderGID is the sending process's group, as verified by the kernel with
	// SenderPID; it means nothing when SenderPID is 0.
	SenderGID int
	// Descriptors are the descriptors the datagram brought — the ones it carried,
	// a pidfd on its sender —, which the caller owns; nil when it brought none.
	Descriptors *DescriptorsValue
}

type PTYValue struct {
	// Rows is the number of character rows.
	Rows uint16
	// Cols is the number of character columns.
	Cols uint16
}

type Process interface {
	// PID reports the process identifier of the leader.
	PID() int
	// Wait blocks until the process exits and returns its ExitValue — the real
	// one even when a running Reaper collected the child first. It is safe
	// to call once; concurrent or repeated calls observe the same outcome. Under
	// StdioCapture it returns only after every captured byte has reached the
	// caller's writers; if a writer itself failed, the ExitValue still reports the
	// real exit status and the error is StdioCaptureFailed. A process the child
	// left behind can hold its output pipe past the exit: Spec.DrainGrace bounds
	// that wait, after which the pipes are closed and the error, beside the real
	// ExitValue, is StdioDrainTimeout.
	Wait() (ExitValue, error)
	// Signal delivers sig to the leader process only.
	Signal(sig Signal) error
	// SignalGroup delivers sig to the leader's entire process group (kill(-pgid,
	// sig)), reaching forked grandchildren — the KillMode=control-group analogue.
	// On Windows a Setpgid child's console process group receives the matching
	// console control event instead — CTRL_C for SIGINT, CTRL_BREAK for SIGTERM,
	// SIGHUP and SIGQUIT — and SIGKILL, or any signal to a child without its own
	// group, reaches the leader alone.
	SignalGroup(sig Signal) error
	// Stop terminates the process group gracefully: it sends sig, waits up to
	// grace for exit, then escalates to SIGKILL. It returns when the process has
	// exited or ctx is cancelled. On Windows sig reaches a Setpgid child as its
	// console control event, as SignalGroup sends it, and the escalation is
	// TerminateProcess.
	Stop(ctx context.Context, grace time.Duration, sig Signal) error
}

type ProcessHandle interface {
	// Handle returns a new descriptor for the process, which the caller owns and
	// closes: a pidfd on Linux — readable once the process exits, so it can be
	// polled, or passed to another process — and a duplicated process HANDLE on
	// Windows. It reports false where none is available: a kernel without pidfd,
	// another platform, or a process already reaped.
	Handle() (*os.File, bool)
	// SignalHandle delivers sig through the process's kernel handle
	// (pidfd_send_signal on Linux), never by pid: once the process is reaped it
	// fails with SignalFailed wrapping ESRCH instead of reaching a process that
	// reused the pid. It returns HandleUnavailable where the kernel gave no handle,
	// and UnsupportedPlatform off Linux and Windows.
	SignalHandle(sig Signal) error
}

type Reaper interface {
	// Start begins a background SIGCHLD-driven loop that reaps children as they
	// exit. It is idempotent: a second Start while running is a no-op.
	Start()
	// Stop ends the background loop after a final draining sweep, so shutdown
	// leaves no un-reaped zombies. It is safe to call without a prior Start.
	Stop()
	// ReapOnce performs a single non-blocking sweep and reports how many
	// children were reaped. It is safe to call concurrently with the loop.
	ReapOnce() (int, error)
}

type Resource int

type ResultValue struct {
	// Exit is the child's ExitValue.
	Exit ExitValue
	// Stdout is the first RunValue.MaxOutputBytes bytes the child wrote to its standard output.
	Stdout []byte
	// Stderr is the first RunValue.MaxOutputBytes bytes the child wrote to its standard error.
	Stderr []byte
	// Truncated reports whether either stream wrote more than MaxOutputBytes, the
	// rest of it read and discarded.
	Truncated bool
}

type RunValue struct {
	// MaxOutputBytes is the number of bytes kept from each of stdout and stderr.
	// The child's output past it is read and discarded, so the child never blocks
	// on a full pipe and the caller never holds more. It must be positive: Run
	// refuses zero with InvalidSpec (ADR 0031).
	MaxOutputBytes int
	// Grace is how long a child whose run was cancelled is given between SIGTERM
	// and SIGKILL; zero or less escalates at once.
	Grace time.Duration
}

type SandboxValue struct {
	// Namespaces are the namespaces the child is cloned into (systemd
	// PrivateUsers=, PrivatePIDs=, PrivateMounts=, PrivateIPC=, ProtectHostname=,
	// PrivateNetwork=, ProtectControlGroups=). A mount namespace is unshared
	// with every mount of it made private first, so nothing the child mounts
	// propagates back. Without NamespaceUser, an unprivileged supervisor's
	// clone is refused by the kernel.
	Namespaces Namespace
	// UIDMap maps the user namespace's uids to the supervisor's (NamespaceUser).
	// Empty maps the namespace's uid 0 to the supervisor's effective uid, one id
	// wide — the one mapping an unprivileged supervisor may write.
	UIDMap []IDMapValue
	// GIDMap maps the user namespace's gids, as UIDMap maps the uids; setgroups(2)
	// is denied in the namespace.
	GIDMap []IDMapValue
	// Mounts are made in order in the child's mount namespace, which they
	// require (NamespaceMount).
	Mounts []MountValue
	// Root, when not empty, is the absolute directory the child pivots into
	// after its Mounts (systemd RootDirectory=, through pivot_root(2)); the old
	// root is detached. Spec.Path and Spec.Dir are then paths inside it, and
	// Spec.Path must hold a '/'. It requires NamespaceMount.
	Root string
	// Capabilities, when non-nil, bounds the child's capabilities; nil leaves
	// them as inherited.
	Capabilities *CapabilitiesValue
	// NoNewPrivileges sets no_new_privs (systemd NoNewPrivileges=): no execve of
	// the child or its descendants gains a privilege. Landlock and Seccomp set
	// it whatever this says, as the kernel requires of an unprivileged caller.
	NoNewPrivileges bool
	// Landlock, when non-nil, restricts the child's access to the filesystem.
	Landlock *LandlockValue
	// Seccomp, when non-nil, filters the child's system calls.
	Seccomp *SeccompValue
}

type SchedPolicy int

type SchedulingValue struct {
	// Policy is the CPU scheduling policy.
	Policy SchedPolicy
	// Priority is the static priority of SchedFIFO and SchedRR (1 to 99 on Linux,
	// 0 to 31 on FreeBSD); it must be 0 for every other policy.
	Priority int
	// IOClass is the I/O scheduling class; IOClassNone leaves the kernel's
	// default, derived from the CPU niceness.
	IOClass IOClass
	// IOPriority is the level within IOClassRealTime or IOClassBestEffort, from 0
	// (highest) to 7 (lowest).
	IOPriority int
}

type SeccompAction uint8

type SeccompValue struct {
	// Default is the action of every call Syscalls does not name.
	Default SeccompAction
	// Syscalls are the calls Action applies to, by their Linux names ("mkdirat").
	// A name no supported architecture knows is InvalidSpec; one this
	// architecture lacks matches nothing.
	Syscalls []string
	// Action is the action of the calls Syscalls names; it must differ from
	// Default.
	Action SeccompAction
	// Errno is the error number SeccompErrno returns, 1 to 4095; zero is EPERM.
	Errno int
}

type Signal int

type Spec struct {
	// Path is the executable to run. Required. A value containing a path
	// separator is a file path, taken as written (a relative one is resolved
	// against Dir). A bare name — "go", "sh" — is searched in the PATH the
	// CHILD will see: the PATH entry of Env whenever Env names one (an
	// explicitly empty PATH= searches nothing), the parent's only when Env
	// names none (including when Env is nil). os/exec's rules apply: the first
	// executable in PATH order wins, and a match found only through a relative
	// entry ("." or an empty one) is refused with exec.ErrDot.
	Path string
	// Args is the full argv including argv[0]; when empty the service uses
	// [Spec.Path] — the name as written, not the resolved file — as the sole
	// argument.
	Args []string
	// Dir is the working directory; empty means inherit the parent's.
	Dir string
	// Env is the explicit environment; nil yields an empty environment, never
	// implicit inheritance, so a spawned service starts from a known state. A key
	// set more than once keeps its last value, at the place of its last
	// occurrence, as os/exec reads append(os.Environ(), "K=v"). A key beginning
	// __KITSUNIUM_SDK_PROC_, in any case, is the SDK's own spawn protocol and is
	// refused with ReservedEnv before any fork.
	Env []string

	// User is the name or numeric uid to setuid to; empty leaves the parent's.
	// The child takes the user's primary gid unless Group names one. A numeric
	// uid with no passwd entry has no primary gid, so it needs an explicit
	// Group: alone it fails with UnknownUser, never falling back to gid 0.
	User string
	// Group is the name or numeric gid to setgid to. Empty leaves the user's
	// primary gid when User is set, and the parent's when it is not.
	Group string
	// Groups are supplementary group names or gids (systemd SupplementaryGroups=).
	Groups []string

	// Setpgid places the child in its own process group, enabling group-kill of
	// the whole tree (systemd KillMode=control-group without cgroups).
	Setpgid bool
	// Setsid starts the child in a new session detached from the controlling tty.
	Setsid bool
	// DieWithParent, when non-zero, is the signal the child receives when the
	// supervisor dies — a SIGKILL or a crash included, where no Stop runs. Linux and
	// FreeBSD set the kernel's parent-death signal (PR_SET_PDEATHSIG, procctl
	// PROC_PDEATHSIG_CTL), which fires when the THREAD that forked the child exits:
	// the Go runtime keeps its threads, but one whose goroutine ends while locked to
	// it exits with it. Windows places the child in a Job Object with
	// KILL_ON_JOB_CLOSE whose handle stays open for the supervisor's life, so any
	// non-zero signal means termination there. Elsewhere a non-zero value surfaces
	// UnsupportedPlatform before anything is spawned. The zero Signal requests
	// nothing.
	DieWithParent Signal

	// Umask, when non-nil, is the file-creation mask applied to the child
	// (systemd UMask=).
	Umask *int
	// Nice, when non-nil, is the scheduling-priority adjustment applied to the
	// child (systemd Nice=). On Windows it selects the child's priority class at
	// creation: -10 and below HIGH, below 0 ABOVE_NORMAL, 0 NORMAL, 1 to 10
	// BELOW_NORMAL, above 10 IDLE.
	Nice *int
	// OOMScoreAdj, when non-nil, is the /proc/<pid>/oom_score_adj value applied
	// to the child (systemd OOMScoreAdjust=).
	OOMScoreAdj *int
	// Scheduling, when non-nil, is the CPU scheduling policy and the I/O priority
	// applied to the child (systemd CPUSchedulingPolicy=, CPUSchedulingPriority=,
	// IOSchedulingClass=, IOSchedulingPriority=), on the live pid beside Nice. Linux
	// applies both (sched_setscheduler, ioprio_set); FreeBSD applies SchedFIFO,
	// SchedRR and SchedIdle through rtprio(2); every other platform refuses a Policy
	// other than SchedOther or an IOClass other than IOClassNone with
	// UnsupportedPlatform before spawning. An undefined policy or class, or an I/O
	// level past 7, is InvalidSpec; a refusal by the kernel (a realtime policy
	// without CAP_SYS_NICE) is RlimitFailed and the child is torn down.
	Scheduling *SchedulingValue
	// Rlimits are per-resource soft/hard limits applied post-fork, pre-exec
	// (systemd Limit*=); resources unsupported on the platform surface a typed
	// error rather than silently no-op. Without a ResourceNoFile entry the child
	// does not inherit the supervisor's open-file soft limit: the Go runtime
	// raises its own to the hard limit at start and puts the original back in
	// every child it forks, until rlimit.KeepRaisedNoFile is called.
	Rlimits map[Resource]LimitValue

	// CgroupPath, when non-empty, is an already-created cgroup v2 directory the
	// child is placed into BEFORE exec, so controller limits (MemoryMax/TasksMax/
	// …) apply from its first instruction — closing the unconfined window that a
	// post-spawn Group.Add(pid) leaves open (systemd places the unit's payload in
	// its cgroup the same way). On Linux 5.7 and later the child is cloned straight
	// into the group (clone3 with CLONE_INTO_CGROUP); on an older kernel, or one
	// whose filter refuses clone3, the pre-exec trampoline writes its pid to
	// <CgroupPath>/cgroup.procs. Linux-only: a non-empty
	// value on any other GOOS surfaces UnsupportedPlatform; a path that is missing,
	// not a cgroup v2 directory, or not delegated surfaces a typed cgroup error
	// rather than spawning unconfined.
	CgroupPath string

	// Stdio selects how the child's standard streams are wired: StdioInherit
	// (default — share the parent's), StdioNull (discard to the null device),
	// StdioCapture (use the Stdout/Stderr/Stdin members below), or StdioPTY (one
	// pseudo-terminal for all three, sized by PTY). systemd
	// StandardOutput=/StandardError=/StandardInput= is the analogue.
	Stdio StdioMode
	// Stdout, when Stdio is StdioCapture, receives the child's standard output;
	// a nil writer discards that stream to the null device.
	Stdout io.Writer
	// Stderr, when Stdio is StdioCapture, receives the child's standard error;
	// a nil writer discards that stream to the null device.
	Stderr io.Writer
	// Stdin, when Stdio is StdioCapture, is copied to the child's standard input;
	// a nil reader gives the child an immediate-EOF stdin. The reader should be
	// EOF-terminating (a buffer, file, or strings.Reader); the copier closes the
	// child's stdin at EOF and never blocks Wait.
	Stdin io.Reader
	// PTY, when Stdio is StdioPTY, is the initial window size of the child's
	// pseudo-terminal; nil leaves the size a new terminal has (zero by zero). It is
	// ignored in every other mode.
	PTY *PTYValue
	// DrainGrace bounds how long Wait waits for the StdioCapture copiers once the
	// exit status is in hand. A process the child left behind that inherited its
	// stdout or stderr — a daemon, `sleep 60 &` — keeps the pipe open after the
	// child exits; when the grace closes, Wait closes the parent's pipe ends and
	// returns the real ExitValue with StdioDrainTimeout. The zero value is the
	// bounded default of one second (ADR 0031); a negative value waits for every
	// byte however long the pipes stay open.
	DrainGrace time.Duration

	// ExtraFiles are additional open files inherited by the child, in order,
	// starting at file descriptor 3 (after stdin/stdout/stderr). This is the
	// mechanism behind socket activation (sd_listen_fds): an activator binds
	// listening sockets and passes them here, then sets LISTEN_FDS/LISTEN_PID in
	// Env so the child finds them at fd 3..3+len-1. nil means no extra fds. They
	// are the only descriptors past stdio the child gets, unless FDs says otherwise.
	ExtraFiles []*os.File
	// PIDEnv names variables the child is given set to its own PID, in decimal:
	// the spawn sets them after the fork, before the program runs — what
	// LISTEN_PID and WATCHDOG_PID need, since no parent knows a child's PID
	// before forking it. A name here replaces the same name in Env. Setting one
	// routes the spawn through the trampoline, as Rlimits and Umask do; Windows
	// refuses it with UnsupportedPlatform. A name that is empty or holds '=',
	// ',' or NUL is InvalidSpec, one beginning __KITSUNIUM_SDK_PROC_ ReservedEnv.
	PIDEnv []string
	// FDs says which of the supervisor's descriptors the child inherits besides its
	// stdio and ExtraFiles. FDsSealed — the zero value — gives it none: Start first
	// marks every descriptor of the supervisor from 3 up close-on-exec, one
	// close_range(CLOSE_RANGE_CLOEXEC) on Linux 5.11 and later and on FreeBSD,
	// otherwise a walk of /proc/self/fd (Linux, illumos, Solaris) or /dev/fd (darwin
	// and the BSDs). The mark is process-wide and closes nothing: the supervisor keeps
	// using its descriptors. FDsInherited lets the child inherit every descriptor that
	// lacks close-on-exec, as fork/exec does by default — after a sealed spawn, only
	// those opened without close-on-exec since. Windows passes a child only the
	// handles it is given, so the field changes nothing there.
	FDs FDPolicy
	// Sandbox, when non-nil, is the isolation the child is spawned under:
	// namespaces, mounts, a new root, capabilities, no_new_privs, Landlock and
	// seccomp, applied by the spawn's second stage before the program runs, the
	// seccomp filter last. The identity (User, Group, Groups) is then taken by
	// that stage too, after the capability bounding set is cut, and FDs must be
	// FDsSealed. Linux on amd64 and arm64 applies it; any other platform refuses
	// it with UnsupportedPlatform before anything is spawned, a kernel lacking a
	// part of it with SandboxUnavailable, and a step that fails in the child with
	// SandboxFailed — the program never runs unconfined.
	Sandbox *SandboxValue
}

type StdioMode uint8

type Terminal interface {
	// TTY returns the master side of the child's pseudo-terminal: what the child
	// writes is read from it, and what is written to it is the child's input. The
	// caller owns it and closes it; it is nil for a child started without
	// StdioPTY.
	TTY() *os.File
	// Resize sets the terminal's window size (TIOCSWINSZ), and the kernel sends
	// the child SIGWINCH. It returns PTYFailed for a child started without
	// StdioPTY or a size the kernel refuses.
	Resize(rows, cols uint16) error
	// Size reads the terminal's current window size (TIOCGWINSZ).
	Size() (PTYValue, error)
}

type UsageValue struct {
	// MinorFaults counts the page faults served without I/O (ru_minflt).
	MinorFaults uint64
	// MajorFaults counts the page faults that needed I/O (ru_majflt).
	MajorFaults uint64
	// InBlock counts the block input operations (ru_inblock).
	InBlock uint64
	// OutBlock counts the block output operations (ru_oublock).
	OutBlock uint64
	// VoluntaryCtxSw counts the times the process gave up the CPU (ru_nvcsw).
	VoluntaryCtxSw uint64
	// InvoluntaryCtxSw counts the times the scheduler took the CPU away (ru_nivcsw).
	InvoluntaryCtxSw uint64
}