@callback constructed_capabilities() :: [ExSandbox.Capability.name()]

Capabilities this mechanism constructs for whatever it runs.

Optional; a mechanism that omits it constructs nothing as far as the gate is concerned, which is the safe direction and is exactly the pre-existing behaviour.

⚠️ Not the inverse-named twin of required_capabilities/0 — the opposite claim. See the moduledoc. A mechanism that lists a name here is asserting that a sandbox it starts is subject to that confinement even on a host whose own probe reports it unavailable.

⚠️ Nothing in this behaviour verifies the claim. A mechanism that lists a name it does not build has widened its own gate, and the compiler cannot tell. ExSandbox.Conformance is what establishes such a claim, by observing a breach being stopped rather than by confirming a limiter was invoked — the discipline 005 R9b exists to enforce, where a cap was applied, silently lost across an exec, and the process allocated 300 MB under a nominal 100 MB cap and exited 0. Until a mechanism passes conformance, a name here is a promise backed only by that mechanism's own tests.

@callback destroy(ExSandbox.Sandbox.t()) :: :ok | {:error, term()}

Destroys the sandbox and releases its resources.

Must be idempotent: a second destroy returns :ok rather than an error (003-FR-013). A cleanup path that errors on "already gone" turns every crash-recovery sweep into a source of spurious failures.

@callback execute(
  ExSandbox.Sandbox.t(),
  {cmd :: String.t(), args :: [String.t()]},
  opts :: keyword()
) ::
  {:ok, completion()}
  | {:error, {:could_not_run, term()}}
  | {:error, {:limit_exceeded, :wall_clock | :memory | :cpu}}

Runs {cmd, args} inside a running sandbox and returns what it produced.

This is 012/contracts/execution-seam.md Option A at shape A2: the call returns on completion, and opts[:on_output] may supply a one-argument function receiving output_chunk/0 as output is produced. A caller passing no sink gets exactly the run-to-completion shape, so nothing is paid for what is not used, and 008-FR-061 / 007-FR-023 (in-progress visibility) do not need a second breaking change to this behaviour later.

The three returns are three different facts, and collapsing any two breaks

a requirement

• {:ok, completion} — the command ran. exit_status is the command's own, whatever it is. A non-zero status is a result, not an error.
• {:error, {:could_not_run, reason}} — the command did not run: the sandbox was gone, the binary was not there, the mechanism could not reach in. ⚠️ This is not an exit status and must never be reported as one. 008-FR-016 and 008-FR-026 both rest on it: an implementation that maps "the sandbox was gone" onto a non-zero exit has converted an unperformed check into a failed one, and a failed check consumes a refinement iteration that FR-026 says it must not.
• {:error, {:limit_exceeded, capability}} — the command was stopped by a limit the sandbox was launched under.

Limits are the launch's, never this call's

A mechanism must not read a limit here and enforce it around the command. ExSandbox.Hardening's moduledoc records why: 005 R9b measured a cap silently lost across an intervening exec, allocating 300 MB under a nominal 100 MB cap and exiting 0. A limit re-applied at execution time is a limit applied after the process it governs already exists, which is the shape that fails open. The sandbox is launched under the hardening layer's own command construction -- ExSandbox.Hardening.Linux.build_command/2 on Linux, ExSandbox.Hardening.Darwin.apply/3 on macOS -- and what runs inside it inherits that confinement or the mechanism has none.

Options

• :on_output — (t:output_chunk/0 -> any()), optional.
• :timeout — a wall-clock ceiling for this call, optional. A sandbox that declares its own budget is bounded by that budget regardless.

A mechanism may accept further options; it must not require any.

@callback list_running() :: {:ok, [String.t()]} | {:error, term()}

Every mechanism_ref this mechanism currently believes is running.

Exists for reconciliation after a restart (003-FR-015). Nothing in the happy path calls it, which is exactly why it is specified rather than left to each mechanism to provide or not.

@callback provision(ExSandbox.Sandbox.t()) ::
  {:ok, ExSandbox.Sandbox.t()} | {:error, term()}

Creates the sandbox's resources without starting it.

Returns the sandbox with mechanism_ref set — the opaque handle by which this mechanism will recognise it later.

@callback required_capabilities() :: [ExSandbox.Capability.name()]

Capabilities this mechanism requires of the host.

Optional. A mechanism that omits it is treated as requiring every known capability — see the moduledoc.

@callback start(ExSandbox.Sandbox.t()) :: {:ok, ExSandbox.Sandbox.t()} | {:error, term()}

Starts a provisioned sandbox.

@callback status(ExSandbox.Sandbox.t()) :: {:ok, status()} | {:error, term()}

The sandbox's current state as this mechanism observes it (003-FR-024).

@callback stop(ExSandbox.Sandbox.t()) :: {:ok, ExSandbox.Sandbox.t()} | {:error, term()}

Stops a running sandbox, leaving its resources intact.

@callback usage(ExSandbox.Sandbox.t()) :: {:ok, usage()} | {:error, term()}

Current resource consumption for one sandbox (003-FR-026).