clusterflux-public/docs/task-abi.md

Task ABI

The MVP task ABI is a small, versioned contract between a compiled workflow module and the coordinator-main or node Wasmtime host. It is intentionally narrower than WASI and should grow only when the flagship workflow needs another host operation.

Assignment

Each assignment carries a TaskSpec containing the virtual process and task identity, bundle module, declared Wasm export and ABI version, serialized arguments, required capabilities and artifacts, selected environment, and VFS epoch. The node rejects a missing or incompatible spec rather than guessing an entrypoint.

SDK task macros generate exports that decode versioned boundary values, invoke the Rust function, and encode the result. Values crossing a task boundary are limited to serializable data and Disasmer handles; host-only objects fail at compile time.

Host imports

The current guest imports cover task spawn/join, command execution, cancellation observation, source snapshots, VFS file operations, artifact publication, and debug probes. Every import validates memory ranges and payload sizes. The coordinator main receives only spawn/join, waiting, bounded state, and debug controls; node hosts check the assignment's declared capabilities before performing source, command, network, or artifact operations.

disasmer.command_run_v1 runs a command through the selected environment backend. On Linux, a task assigned to an environment requiring rootless Podman uses the normal Podman assignment path. The hosted community policy does not grant this on managed infrastructure; a user node may grant it for its own machine.

Lifecycle

Cooperative cancellation is visible to guest code at a host boundary. Forced abort arms Wasmtime epoch interruption and also terminates active environment work. Debug freeze and resume synchronize at acknowledged host or Wasmtime epoch boundaries. These controls do not claim instruction-accurate source stepping. Each task assignment captures a restart-compatibility hash and clean VFS entry boundary. DAP task restart rebuilds the bundle and accepts edited code only when the task ABI, declared capabilities, environment, arguments, handles, and VFS boundary remain compatible.