clusterflux-public/docs/architecture.md

Architecture

Clusterflux separates a control plane from execution nodes.

Coordinator

The coordinator owns identity scope, one-active-process admission, task placement, attempt history, Debug Epoch coordination, VFS metadata, artifact metadata, quotas, and secure relay reservations. Its async main may park and wake without consuming node compute.

The coordinator does not execute arbitrary native commands or hosted containers. It also does not become a durable artifact store merely because it coordinates a download.

Nodes

A node is an enrolled public-key identity. It reports capabilities and periodic heartbeats. The coordinator derives whether it is live from the last accepted heartbeat; a client-supplied "online" field is not placement authority.

Nodes resolve bundle environments, execute Wasm tasks, run native commands, and retain artifact bytes. A node must prove the tenant, project, process, task, and key scope on every signed request.

Virtual process and tasks

A Coordinator Project admits one active virtual process. The process contains:

• one coordinator-hosted async main;
• logical task instances created by that main;
• one or more attempts for each logical task;
• joins tied to the logical task, not to an individual attempt.

"FailFast" makes a terminal failure visible to the join immediately. "AwaitOperator" keeps the join pending while an operator accepts, cancels, or restarts the failed task. Restart creates a distinct attempt but preserves the logical task identity.

A terminal process releases the active slot automatically. A task parked for an operator is not terminal and continues to occupy the slot.

Durable and live state

Projects, identities, credentials, permissions, hosted policy records, relay period usage, and relay reservation accounting may be stored in Postgres. Active processes, task placement, Debug Epochs, transient VFS state, relay byte streams, and live node state are bounded in memory and are not reconstructed as running after a coordinator restart. Pre-restart relay reservations are reconciled as abandoned before new links can be issued.

Protocol lanes

Human clients use scoped sessions. Agents and nodes use separate signed public-key identities. Operator actions use a separate administrative credential. Authority comes from the authenticated lane and server-side scope, never from identity fields in an untrusted request body.