Public dry run dryrun-a43e907efd9d

Source commit: a43e907efd9d1561c23fe73499478e881f868355

Public tree identity: sha256:453dea30195485dd8939f575a69b39f4bb7acd84c4df23f8aa29b55d044f2673

docs/architecture.md

@@ -0,0 +1,55 @@
+# 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, and hosted policy records may
+be stored in Postgres. Active processes, task placement, Debug Epochs, transient
+VFS state, relay reservations, and live node state are bounded in memory and are
+not reconstructed as running after a coordinator restart.
+
+## 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.