Public release release-98d969b26488

Source commit: 98d969b26488b4cda8b2381fa870276a00ca98ea

Public tree identity: sha256:d02dd1e8d3547a489bb300741bed544bdc60bb8fe0bd541fd43ce9bfa7129a3e

docs/architecture.md

@@ -0,0 +1,57 @@
+# 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.