@spec drop_bounding(Linx.Process.t(), Enumerable.t()) ::
  :ok
  | {:error, :not_ready | :running | :no_process | {:bad_capability, term()}}

Drops capabilities from the child thread's bounding set on a parked Linx.Process session.

caps is a MapSet or list of :cap_* atoms. The operation is one-way (prctl(PR_CAPBSET_DROP)) — the kernel will refuse to re-add a dropped cap via any subsequent verb on the same thread, even via set_thread_sets/2.

Errors

• {:error, :not_ready} — session not yet at the checkpoint.
• {:error, :running} — past proceed/1, the child is in execve'd land.
• {:error, :no_process} — session has ended.
• {:error, {:bad_capability, atom}} — caps contains an atom Linx doesn't recognise. Validation happens before anything is sent to the agent.

Kernel-level failures (the workload didn't have the required privilege to drop a particular cap, etc.) arrive asynchronously as {:linx_process, :error, errno, :cap_drop_bounding} on the session's owner mailbox, the same shape as other pre-execve failures.

Example

:ok = Linx.Capabilities.drop_bounding(session,
  [:cap_sys_admin, :cap_sys_module, :cap_dac_override])

@spec read(pos_integer() | :self) ::
  {:ok, Linx.Capabilities.State.t()} | {:error, Linx.Capabilities.Error.t()}

Reads a process's capability sets from /proc/<pid>/status.

Accepts a positive integer pid, or :self as a convenience for the BEAM's own status. Returns {:ok, %Linx.Capabilities.State{}} on success, or {:error, %Linx.Capabilities.Error{}} if the procfs read failed or the file didn't contain the five Cap*: lines we expected.

Examples

iex> {:ok, %Linx.Capabilities.State{} = state} = Linx.Capabilities.read(:self)
iex> is_struct(state.effective, MapSet) and is_struct(state.bounding, MapSet)
true

# Bogus pid -> structured error.
iex> {:error, %Linx.Capabilities.Error{errno: :enoent}} =
...>   Linx.Capabilities.read(1_234_567_890)
iex> true
true

Forward compatibility

If the kernel reports a bit that isn't in Linx's 41-entry table (a newer kernel adding caps Linx hasn't catalogued), the bit is silently dropped from the returned MapSets and a single Logger.warning/1 is emitted. The returned %State{} is still valid for every cap Linx does know about.

@spec set_ambient(Linx.Process.t(), Enumerable.t()) ::
  :ok
  | {:error, :not_ready | :running | :no_process | {:bad_capability, term()}}

Sets the child thread's ambient capability set on a parked Linx.Process session.

caps is a MapSet or list of :cap_* atoms. The ambient set is replaced (the kernel only exposes per-cap RAISE/LOWER plus a global CLEAR_ALL, so the natural shape is "clear then raise each requested cap").

Ambient caps are the mechanism that lets a non-root, no-file-cap binary still inherit capabilities across execve — useful when you want a workload to start with e.g. :cap_net_bind_service but don't want to put file caps on the binary or run it as root. See capabilities(7) "Ambient capabilities" for the full rules (notably: every ambient cap must also be in the permitted and inheritable sets, or the raise fails).

Errors

Same shape as drop_bounding/2. Kernel failures (a raise that fails because the cap isn't in permitted+inheritable, etc.) arrive as {:linx_process, :error, errno, :cap_set_ambient}.

@spec set_thread_sets(
  Linx.Process.t(),
  keyword()
) ::
  :ok
  | {:error,
     :not_ready
     | :running
     | :no_process
     | {:bad_capability, term()}
     | {:bad_thread_sets, {:missing, atom()}}}

Sets the child thread's effective, permitted, and inheritable capability sets on a parked Linx.Process session.

opts is a keyword list with all three required keys: :effective, :permitted, :inheritable. Each value is a MapSet or list of :cap_* atoms (use [] or MapSet.new() to clear a set).

Implemented via capset(2) in the agent. The kernel enforces the invariants documented in capabilities(7) — notably that :effective ⊆ :permitted and :inheritable ⊆ :permitted ∪ I_old. Violations arrive as {:linx_process, :error, :einval, :cap_set_thread} on the owner mailbox.

Errors

Same shape as drop_bounding/2. Additional caller-side errors:

• {:error, {:bad_thread_sets, {:missing, key}}} — one of :effective, :permitted, :inheritable was omitted.
• {:error, {:bad_capability, atom}} — any of the three values contained an unknown cap atom.

@spec supported?() :: boolean()

Returns true iff Linux capabilities are inspectable on this host — i.e. /proc/self/status contains a CapBnd: line.

True on every Linux ≥ 2.6.25 (every kernel Linx targets). Useful as a precondition guard or in setup checks; this module's verbs don't gate on it themselves.