A tasklet: one processing stage of a relay's graph, run once per input and declared with use.

defmodule Echo do
  use Flezha.SDK.Tasklet, name: "echo"

  @impl true
  def run(input, state, ctx) do
    emit(ctx, "echo: " <> input)
    {:ok, state}
  end
end

use declares this behaviour, defines name/0 and the zero-arity callbacks its options name, imports the ctx functions, and makes available a state block, which writes init_state/1 and state_from_json/1, and defchange, the one way to change state (Flezha.SDK.State); see __using__/1. The author writes run/3 and any other callback that takes arguments, each under @impl true.

Callbacks. Mandatory: name/0, init_state/1 (the cell key or nil; use answers nil for a module that declares no state), run/3 (input, state, ctx) returning {:ok, new_state} | {:error, reason} | {:error, {:non_retryable, reason}}. Optional, with defaults: cell_keys/0 (static keyset, []; a keyset is refused as topology.cells_for_missing without cells_for/1, which names the keys an input routes to), mailbox_capacity/0 (1024, env FLEZHA_MAILBOX_CAPACITY, range 1..=1_048_576), max_cells/0 (100_000 — the cap on a dynamic node's live Cells; at it a new key's input is dropped and counted), idle_ttl_seconds/0 (nil — a dynamic Cell idle past that many whole seconds is evicted destructively by its Relay's sweep; nil never evicts). Dynamic typing collapses the Rust type tokens — Input/Output/State are plain terms.

Persistence: a tasklet that exports apply_change/2 is changeful — its state is rebuilt by folding recorded changes. In the use form each defchange generates one fold clause and its recorder; without one the tasklet is the reference's NoChange: its state is a plain term nothing persists. compact_after_bytes/0 (8 MiB) is the per-Cell WAL size at which the controller solicits a snapshot; state_from_json/1 turns a JSON object read back from the controller (a migration, init_values) into this tasklet's state term, the object itself by default.

Schema: schema_version/0 (1) is stamped on every record and resolved per record on restore against min_readable_schema_version/0 (the version itself); a record between the floor and the version is handed to migrate_state/2 (a snapshot) or migrate_change/2 (a change) with the stamped version and the DECODED term — this SDK's body codec is the language's own — answering {:ok, term} at the running version or {:error, reason}. Both default to refusing, so a floor declared without its migration fails at the first old record.

Time: the clock Flezha.SDK.Ctx.now/1 serves follows from what the tasklet writes — event time when it defines event_time/1 (what that answers for the input), the logical clock (the Cell's durable change seq) when logical_clock/0 answers true, the epoch millisecond at dispatch entry otherwise. A logical clock on a changeless tasklet is refused at registration as topology.unservable_clock, and both clocks at once as topology.two_clocks, which the use form refuses at compile time instead. Timers: on_timer/3 (a Flezha.SDK.TimerFiring, the state, a ctx) answers what run/3 answers and is what a timer registered through the ctx fires into; max_timers_per_cell/0 (10_000) bounds a Cell's pending set, and an item whose registrations pass it fails, not retried, when the core settles it.

Saga: compensate/3 (the outputs the Cell released, the state, a ctx) is the undo a steps relay runs, in reverse completion order, when it unwinds after partial progress. A tasklet declaring none has nothing to undo. A crash-resumed unwind reconstructs completed stages with EMPTY outputs — a tasklet's collected output was never durable — so a hook that records an undo must do so unconditionally rather than from what it is handed.

The reference form

A module may instead write @behaviour Flezha.SDK.Tasklet and every callback by hand, name/0 included, recording a change through its own apply_change/2 and Flezha.SDK.Ctx.apply/3. It registers and runs as a use module does; the use form refuses a hand-written apply_change/2.