@spec await_termination(result()) :: :ok | {:error, Flezha.SDK.Error.t()}

Block until the runner terminates.

@spec call(result() | pid() | atom(), String.t(), String.t(), term()) ::
  {:ok, term()} | {:error, Flezha.SDK.Error.t()}

Call the entry channel channel of relay_id with value, through the controller under the same role check as send/5, answering what the relay answers: {:ok, answer} with a JSON value, a string for text, the bytes for the binary formats, or %{"accepted" => true} from a channel no output answers. value is encoded as an output with no serializer of its own encodes it.

runner is a handle, or the runner server's pid or name.

A child spec wrapping create → register → start for the host application's supervision tree: namespace:, relays:, transport: and namespace_secret:. The supervised process is the runner. A runner runs once per BEAM: one that stops or crashes ends its session, and the restart that follows is refused, so the failure reaches the node, which is the unit to restart. The controller moves the relays meanwhile.

@spec close(result()) :: :ok

Ship each relay's state, end the session and release the slot. A runner runs once per BEAM: a later start in this node is refused as runtime.core_shut_down. A never-started handle is a no-op.

@spec create_runner(String.t(), keyword()) :: result()

Create a runner handle. No connection, no slot claim, no processes.

@spec register_factory(result(), module()) :: result()

Declare a relay: a module of the Flezha.SDK.Relay behaviour. Legal before and after start/1.

Its declaration is judged here by flz_core, the check every SDK's builder is judged by, and declared to the live core when the runner is started.

@spec relays(result() | pid() | atom()) ::
  {:ok, [String.t()]} | {:error, Flezha.SDK.Error.t()}

The ids of the relay instances bound on this runner now, a partition member by its member id, read without the controller.

@spec run(result()) :: :ok | {:error, Flezha.SDK.Error.t()}

start/1 then await_termination/1.

@spec send(result() | pid() | atom(), String.t(), String.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, Flezha.SDK.Error.t()}

Send message to the entry channel channel of relay_id.

Through the controller by default, under the same role check as Flezha.SDK.Control, answering its verdict: {:ok, %{"to" => relay, "verdict" => "delivered" | "absorbed" | "suspended"}}. Options:

• msg_id: the message's id, stamped as flz.msg_id: a relay whose input log still holds an input of this id absorbs the repeat.
• key: the partition key whose member of a partition group takes it.
• local: true in process, without the controller: the message is on no disk, is lost if the runner stops before handling it, and a relay's input log does not cover it. Answers {:ok, nil}; refused with runtime.relay_not_local for a relay this runner does not hold, and with usage.options_conflict beside msg_id: or key:.

runner is a handle, or the runner server's pid or name.

@spec server(result() | pid() | atom()) ::
  {:ok, pid() | atom()} | {:error, Flezha.SDK.Error.t()}

The live runner process behind a handle: runtime.runner_not_started before start/1, and a refused handle's own error unchanged.

The one place a caller outside this module reads the handle's server, so the struct's shape stays this module's business.

@spec start(result()) :: result()

Claim the runner slot and connect. The loser gets runtime.runner_already_running naming the namespace.

@spec unregister_factory(result(), module()) :: result()

Remove a declared relay — the inverse of register_factory/2, taking what it took.