clusterflux-public/docs/architecture.md

Architecture

Disasmer presents a distributed workflow as one virtual process. The workflow program and its tasks are WebAssembly modules; the coordinator, attached nodes, CLI, and debugger are separate host processes.

Components

• The SDK and macros turn Rust workflow functions into versioned Wasm exports.
• The CLI builds and validates a bounded bundle, creates a virtual process, and launches its selected entrypoint as the coordinator main.
• The coordinator owns identity, authorization, scheduling, process state, and debug epochs. It executes only the capless coordinator-main Wasm: that main may spawn/join tasks, wait, log bounded state, and participate in debugging, but cannot run commands, read source or host files, use sockets, or obtain secrets. The coordinator does not retain artifact bytes.
• Attached nodes verify assignments and execute Wasm with Wasmtime. Host operations are available only through imports backed by granted capabilities.
• The DAP adapter maps a virtual process and its tasks to ordinary debugger processes and threads without pretending that source-level stepping exists.

The standalone Core coordinator is the public self-hosted service. The Hosted coordinator wraps the same Core service with private identity-provider, community-policy, operator, and deployment code. Public/private is a source distribution boundary, not an authority boundary.

State

Durable Postgres state contains tenants, users, projects, credentials, permissions, source-provider configuration, and service policy records. Active virtual processes, assignments, debug epochs, transient VFS views, and artifact locations are intentionally ephemeral for the MVP. Restarting the coordinator therefore preserves identity and project configuration but ends active work.

Execution and placement

Wasm is the execution substrate, not a capability. The coordinator main uses a small fixed capless import set. A node task's TaskSpec declares the additional host operations and environment it needs, and a node is eligible only when its reported capabilities satisfy those requirements. For example, a Wasm task may request command execution in a declared Linux environment; a user-attached node with rootless Podman can provide that operation, while hosted community infrastructure denies arbitrary native commands and hosted containers.

The build-system workflow is the MVP wedge. General distributed application runtime features are deliberately outside the initial release.