Mercurius is designed around a small, composable set of ideas.
Mercurius’s architecture is a message‑passing system where every component acts locally and routing emerges from uniform rules.
Architecture
Core Concepts
Mercurius is designed around a small, composable set of ideas:
- A stable, long‑lived workstation acts as the authoritative environment.
- Portals connect to this workstation using a protocol designed for presence, not display.
- State lives on the workstation; interaction happens wherever you are.
- The protocol is optimised for SCTP and efficient over modern networks.
- The system must be secure against DDoS and APT attacks.
The architecture is intentionally minimal. Complexity belongs in the workstation, not in the protocol.
Mercurius rests on one load‑bearing idea: its components behave like Smalltalk objects, but are implemented in C. Every component receives Messages and decides locally what to do — consume the Message, or forward it to a neighbour it owns or is owned by. There are no global dispatch tables, no cross‑cutting calls, and no central coordinator. A Message reaches its destination not because anything routes it, but because each component along the way makes the same local decision. This Smalltalk‑in‑C discipline keeps the protocol small, the system composable, and the architecture predictable under load.
Internal Object Model
Mercurius’s behaviour is an emergent property of its object model. Every component receives Messages and decides locally whether to consume or forward them; no component reaches across the graph. There is no global dispatcher, no routing table, and no procedural pipeline. Delivery, teardown, and lifecycle fall out of this one uniform discipline rather than being enforced by special cases.
For a complete description of the internal structure of Mercurius — the object model, the Iron rules, and the Smalltalk‑in‑C message‑passing discipline — see the Object Model.
The Object Model defines what Mercurius is built from; the coding standards define how those ideas are expressed safely in C. For the implementation‑level rules — covering ownership, lifetimes, error handling, documentation, and safe use of the language — see the C Coding Standards.
Milestones, Waypoints and Rabbits describes how that behaviour is uncovered during development. MWR provides the trail that leads from the architectural map to working demonstrations, ensuring that each refinement of the object model is driven by real behaviour rather than speculative design.
Architectural Requirements
Why SCTP‑only is the right choice for Mercurius
The protocol’s guarantees depend on SCTP semantics, and plain TCP cannot provide these without re‑implementing SCTP in user space. If TCP becomes a first‑class transport, implementers will choose it because it is easier.
This leads to:
- Degraded latency
- Broken prioritisation
- Unpredictable input timing
- A “remote desktop” feel
- The protocol being judged by its worst transport
Mercurius avoids this by depending on SCTP’s modern transport semantics:
- Independent ordered streams
- Message boundaries
- Partial reliability
- No cross‑stream head‑of‑line blocking
- Multi‑homing and stable associations
These are the foundation of:
- Deterministic compositor behaviour
- Responsive input under load
- High‑motion video surfaces
- Relocatable sessions
- Multi‑seat concurrency
Why Vulkan‑only is the right choice for Mercurius
Mercurius requires Vulkan for the same reason it requires SCTP: the system depends on properties that only Vulkan provides natively. The compositor, the Session model, and the rendering pipeline all assume explicit GPU control, predictable synchronisation, and cross‑platform consistency.
Allowing multiple GPU APIs would force the compositor to:
- support multiple backends with incompatible semantics
- fall back to lowest‑common‑denominator rendering
- lose deterministic behaviour due to implicit driver state
- abandon multi‑GPU awareness and migration
- be judged by its weakest renderer
Vulkan provides the architectural guarantees Mercurius depends on:
- Explicit resource ownership — no hidden allocations or global state.
- Deterministic command submission — the compositor knows exactly when work is queued and completed.
- Cross‑platform consistency — Vulkan is the only modern, vendor‑neutral GPU API.
- Zero‑copy surface handling — structured and video surfaces rely on explicit memory control.
- Multi‑GPU enumeration — Sessions can migrate between GPUs because Vulkan exposes devices explicitly.
Software compositing is insufficient: Mercurius is designed for high‑motion video surfaces, GPU‑accelerated compositing, and multi‑session concurrency. A workstation without a Vulkan‑capable GPU is simply not a Mercurius workstation.