refactor(contract)!: hypervisor-agnostic wire — GuestChannel, opaque ready payload, mechanism-only disk roles, no is_instance

Review feedback: the contract must stay generic regardless of the
hypervisor; Firecracker-vs-QEMU is the only distinction the supervisor
should see.

- CreateVmRequest.program_mode (program/instance vocabulary on the wire)
  becomes `optional GuestChannel guest_channel { ready_port }`: a pure
  mechanism request — expose a host⇄guest channel and treat the guest's
  ready signal on ready_port as part of boot. Firecracker instances are
  naturally 'FC without a channel'.
- VmInfo.control_socket_path → guest_channel_path (empty when the VM has no
  channel, which covers QEMU). VmInfo.runtime_version → guest_ready_payload:
  the raw bytes the guest sent, passed through opaquely — the supervisor no
  longer parses the Aleph runtime's msgpack handshake; the agent does
  (runtime_config_from_ready_payload). MicroVM keeps the raw payload and
  takes the ready port as a parameter.
- DiskRole collapses to ROOTFS/EXTRA: which disk is the root device is
  mechanism; code/runtime/data are workload roles the client maps onto
  guest devices via disk order (which it already did).
- VmInfo.is_instance removed (field 18 reserved): agent vocabulary, derived
  from the registry; the guest channel's presence is the registry-miss
  fallback for the /about list labels.
- The Aleph runtime's channel conventions (control port 52, guest API 53)
  move to aleph.vm.utils.runtime_channel, agent-side, and replace the
  hardcoded CONNECT 52 strings.
- packaging: deb package ships grpcio (matches pyproject).

Re-validated live through the split: CreateVm over gRPC reports
ready_payload=b'\x81\xa7version\xa52.0.0' (raw guest msgpack), agent
parses it, config push + run_code('/') → HTTP 200, DeleteVm clean.
Suite: 742 passed, same 9 environment-only failures as base.

Author: odesenfans

docs/plans/2026-06-11-grpc-process-split-design.md

@@ -97,17 +97,31 @@ supervisor-side:
 | guest API process (`{vsock}_53`) | agent |
 | idle expiry / update-watch / teardown decision | agent (already migrated) |
 
-Contract additions (regenerated bindings committed):
-
-- `CreateVmRequest.program_mode: bool` — supervisor uses the program boot
-  flow (vsock init handshake, no cloud-init); carries no Aleph vocabulary.
-- `VmInfo.control_socket_path: string` — host UDS path of the VM's vsock;
-  empty for backends without one.
-- `VmInfo.runtime_version: string` — the version string the guest init
-  reported during the handshake (the agent needs it to format the config
-  push); empty until init signaled / for non-program VMs.
-- `VmInfo.ipv4_gateway` / `ipv6_gateway` — host-side tap addresses, needed
-  by the agent to fill the guest network config it pushes.
+Contract additions (regenerated bindings committed; reworked 2026-06-11 to
+stay hypervisor- and workload-agnostic — review feedback):
+
+- `CreateVmRequest.guest_channel: GuestChannel { ready_port }` — optional
+  host⇄guest control channel (Firecracker vsock today; QEMU could implement
+  it with virtio-vsock). When present, the supervisor exposes the channel
+  and waits for the guest's ready signal on `ready_port` as part of boot.
+  What is spoken over the channel is the client's business. (Replaced the
+  earlier `program_mode: bool`, which leaked the program/instance
+  distinction onto the wire.)
+- `VmInfo.guest_channel_path: string` — host UDS endpoint of the channel;
+  empty when the VM has none (QEMU instances).
+- `VmInfo.guest_ready_payload: bytes` — the raw bytes the guest sent with
+  its ready signal, passed through opaquely; the agent parses the Aleph
+  runtime's msgpack version handshake out of it. (Replaced
+  `runtime_version`, which required the supervisor to parse the payload.)
+- `VmInfo.ipv4_gateway` / `ipv6_gateway` — host-side tap addresses (bare,
+  no prefix), the guest's default routes for the agent's config push.
+- `DiskRole` collapsed to ROOTFS/EXTRA: workload roles (code/runtime/data)
+  are client vocabulary, mapped onto guest devices via disk order.
+- `VmInfo.is_instance` removed (field 18 reserved): the instance/program
+  distinction is derived agent-side from the registry, with the guest
+  channel's presence as the registry-miss fallback for labeling.
+- The Aleph runtime's channel conventions (control port 52, guest API port
+  53) live in `aleph.vm.utils.runtime_channel`, agent-side.
 
 Supervisor side: `pool.create_vm_from_spec` accepts
 `backend=FIRECRACKER, program_mode=True` specs and builds a message-free

packaging/Makefile

@@ -19,7 +19,7 @@ debian-package-code:
 	python3 -m venv build_venv
 	build_venv/bin/pip install   --progress-bar off --upgrade pip setuptools wheel
 	# Fixing this protobuf dependency version to avoid getting CI errors as version 5.29.0 have this compilation issue
-	build_venv/bin/pip install --no-cache-dir  --progress-bar off --target ./aleph-vm/opt/aleph-vm/ 'aleph-message~=1.0.1' 'eth-account==0.10' 'sentry-sdk==1.31.0' 'qmp==1.1.0' 'aleph-superfluid~=0.2.1' 'sqlalchemy[asyncio]>=2.0' 'aiosqlite==0.19.0' 'alembic==1.13.1' 'aiohttp_cors==0.7.0' 'pydantic-settings==2.6.1' 'pyroute2==0.7.12' 'python-cpuid==0.1.0' 'solathon==1.0.2' 'protobuf==5.29.6' 'redis>=4.2.0' 'legacy-cgi>=1.0'
+	build_venv/bin/pip install --no-cache-dir  --progress-bar off --target ./aleph-vm/opt/aleph-vm/ 'aleph-message~=1.0.1' 'eth-account==0.10' 'sentry-sdk==1.31.0' 'qmp==1.1.0' 'aleph-superfluid~=0.2.1' 'sqlalchemy[asyncio]>=2.0' 'aiosqlite==0.19.0' 'alembic==1.13.1' 'aiohttp_cors==0.7.0' 'pydantic-settings==2.6.1' 'pyroute2==0.7.12' 'python-cpuid==0.1.0' 'solathon==1.0.2' 'protobuf==5.29.6' 'grpcio>=1.70,<1.71' 'redis>=4.2.0' 'legacy-cgi>=1.0'
 	build_venv/bin/python3 -m compileall ./aleph-vm/opt/aleph-vm/
 
 debian-package-resources: firecracker-bins vmlinux target/bin/sevctl

proto/supervisor.proto

@@ -141,11 +141,17 @@ message CreateVmRequest {
   optional uint32 numa_node = 11;    // requested placement (0-indexed). Unset = auto. See VmInfo.numa_node for the effective placement.
   bool persistent = 12;              // supervisor wraps in systemd if true
   repeated string ssh_authorized_keys = 13; // guest cloud-init SSH keys (agent-provided)
-  // Program boot flow: the supervisor enables the VMM control socket (vsock),
-  // waits for the guest init's ready signal as part of boot, and reports the
-  // socket in VmInfo.control_socket_path. It carries no Aleph vocabulary: the
-  // payloads the agent exchanges over that socket are opaque to the supervisor.
-  bool program_mode = 14;
+  // Optional host⇄guest control channel (Firecracker vsock today; a QEMU
+  // backend may implement it with virtio-vsock). When present, the supervisor
+  // exposes the channel and waits for the guest's ready signal on
+  // `ready_port` as part of boot: the VM reports RUNNING only after the
+  // signal. What is spoken over the channel is the client's business, opaque
+  // to the supervisor.
+  optional GuestChannel guest_channel = 14;
+}
+
+message GuestChannel {
+  uint32 ready_port = 1;             // the guest connects here to signal readiness
 }
 
 message DiskConfig {
@@ -162,13 +168,14 @@ message DiskConfig {
     FORMAT_SQUASHFS = 3;
   }
 
+  // Mechanism-only roles: the supervisor needs to know which disk is the
+  // root device; everything else is attached in spec order (guest device
+  // names are deterministic from that order, which is how the client maps
+  // its workload semantics — code, data, caches — onto devices).
   enum DiskRole {
     DISK_ROLE_UNSPECIFIED = 0;
     DISK_ROLE_ROOTFS = 1;
-    DISK_ROLE_CODE = 2;
-    DISK_ROLE_RUNTIME = 3;
-    DISK_ROLE_DATA = 4;
-    DISK_ROLE_EXTRA = 5;
+    DISK_ROLE_EXTRA = 2;
   }
 }
 
@@ -223,23 +230,23 @@ message VmInfo {
   uint64 stopping_at_ns = 16;
   uint64 stopped_at_ns = 17;
 
-  // True for instances (full VMs), false for programs/microvms. Independent of
-  // the hypervisor backend: an instance may run under Firecracker or QEMU, so
-  // `backend` alone cannot recover this. Mirrors VmExecution.is_instance.
-  bool is_instance = 18;
+  // Was `is_instance`: the instance/program distinction is client vocabulary,
+  // derived client-side from its own records (or from the guest channel's
+  // presence as a last resort).
+  reserved 18;
 
   ConfidentialMode confidential_mode = 19;   // precise TEE mode; NONE for non-confidential VMs
   repeated GpuDevice gpus = 20;              // exact PCI devices attached to this VM (mirrors HostInfo.gpus)
 
-  // Host UDS path of the VM's control socket (Firecracker vsock). The agent
-  // dials it for guest-level protocols (program config push, code execution)
-  // and binds `<path>_<port>` listeners for guest-initiated connections.
-  // Empty for backends without one (program_mode VMs only today).
-  string control_socket_path = 21;
-  // Version string the guest init reported during the boot handshake; empty
-  // until the init signaled (or for VMs without the handshake). The agent
-  // formats its guest payloads according to this version.
-  string runtime_version = 22;
+  // Host UDS endpoint of the guest control channel (see
+  // CreateVmRequest.guest_channel). The client dials it for guest-level
+  // protocols and binds `<path>_<port>` listeners for guest-initiated
+  // connections. Empty when the VM was created without a channel.
+  string guest_channel_path = 21;
+  // Raw bytes the guest sent with its ready signal, passed through opaquely;
+  // empty until the signal arrived (or for VMs without a channel). The client
+  // interprets them (the Aleph runtime sends its version handshake here).
+  bytes guest_ready_payload = 22;
   // Host-side tap addresses (no prefix). The agent passes them to the guest
   // as default routes in its network configuration push.
   string ipv4_gateway = 23;

src/aleph/vm/controllers/firecracker/spec_program.py

@@ -1,15 +1,16 @@
-"""Message-free Firecracker program controller, driven by a CreateVmSpec.
-
-The supervisor side of the program (microvm) split: boots a Firecracker VM
-from resolved on-disk paths only — no Aleph message, no download, no guest
-configuration. The Aleph-runtime protocols (config push, code execution,
-guest API) are the agent's business, spoken over the vsock control socket
-this VM exposes (reported via VmInfo.control_socket_path).
-
-Drive order is part of the contract with the agent: root device (the
-RUNTIME-role disk), then the CODE-role disk if present, then EXTRA disks in
-spec order. The agent derives guest device names (vdb, vdc, …) from that
-order when it builds its configuration push.
+"""Message-free Firecracker controller for guest-channel VMs, driven by a
+CreateVmSpec.
+
+Boots a Firecracker VM from resolved on-disk paths only — no Aleph message,
+no download, no guest configuration. The guest-level protocols (the Aleph
+config push, code execution, guest API) are the client's business, spoken
+over the vsock channel this VM exposes (reported via
+VmInfo.guest_channel_path); the guest's ready signal on the channel is part
+of boot.
+
+Drive order is part of the contract with the client: the ROOTFS-role disk is
+the root device, then the EXTRA disks in spec order. The client derives guest
+device names (vdb, vdc, …) from that order.
 """
 
 from __future__ import annotations
@@ -41,32 +42,23 @@
 
 @dataclass
 class SpecProgramResources:
-    """Resolved paths for a spec-driven program boot. No download happens
-    here: the agent prepared every file and the spec carries the paths."""
+    """Resolved paths for a spec-driven boot. No download happens here: the
+    client prepared every file and the spec carries the paths."""
 
     kernel_image_path: Path
-    rootfs_path: Path  # the RUNTIME-role disk: a program's root filesystem
-    code_disk: DiskSpec | None
+    rootfs_path: Path
     extra_disks: list[DiskSpec] = field(default_factory=list)
 
     @classmethod
     def from_spec(cls, spec: CreateVmSpec) -> SpecProgramResources:
         kernel_path = spec.kernel_path
         if not str(kernel_path) or str(kernel_path) == ".":
-            raise InvalidBackendError("A program spec requires a kernel_path")
-
-        runtime_disks = [disk for disk in spec.disks if disk.role is DiskRole.RUNTIME]
-        if len(runtime_disks) != 1:
-            raise InvalidBackendError(f"A program spec requires exactly one RUNTIME disk, got {len(runtime_disks)}")
-
-        code_disks = [disk for disk in spec.disks if disk.role is DiskRole.CODE]
-        if len(code_disks) > 1:
-            raise InvalidBackendError(f"A program spec carries at most one CODE disk, got {len(code_disks)}")
+            raise InvalidBackendError("A Firecracker spec requires a kernel_path")
 
+        rootfs = spec.require_rootfs()
         return cls(
             kernel_image_path=kernel_path,
-            rootfs_path=runtime_disks[0].path,
-            code_disk=code_disks[0] if code_disks else None,
+            rootfs_path=rootfs.path,
             extra_disks=[disk for disk in spec.disks if disk.role is DiskRole.EXTRA],
         )
 
@@ -75,7 +67,7 @@ def to_dict(self):
 
 
 class SpecFirecrackerProgram(AlephFirecrackerExecutable[None]):
-    """Spec-driven program microvm: VMM boot + init handshake only."""
+    """Spec-driven guest-channel microvm: VMM boot + ready handshake only."""
 
     resources: SpecProgramResources  # type: ignore[assignment]
     is_instance = False
@@ -106,7 +98,7 @@ async def setup(self) -> None:
         logger.debug("Setup started for spec program VM=%s", self.vm_id)
         await setfacl()
 
-        extra_disks = ([self.resources.code_disk] if self.resources.code_disk else []) + self.resources.extra_disks
+        extra_disks = self.resources.extra_disks
         self._firecracker_config = FirecrackerConfig(
             boot_source=BootSource(
                 kernel_image_path=Path(self.fvm.enable_kernel(self.resources.kernel_image_path)),
@@ -134,8 +126,9 @@ async def setup(self) -> None:
         )
 
     async def wait_for_init(self) -> None:
-        """The init-ready handshake is part of boot for program-mode VMs."""
-        await self.fvm.wait_for_init()
+        """The guest's ready handshake is part of boot for channel VMs."""
+        ready_port = self.spec.guest_channel.ready_port if self.spec.guest_channel else 52
+        await self.fvm.wait_for_init(ready_port=ready_port)
 
     async def start_guest_api(self):
         """Agent-owned across the boundary: the agent binds `<vsock>_53` itself."""

src/aleph/vm/controllers/qemu/instance.py

@@ -151,7 +151,7 @@ def from_spec(cls, spec: "CreateVmSpec", namespace: str) -> "AlephQemuResources"
         resources.volumes = [
             HostVolume(mount=d.mount, path_on_host=d.path, read_only=d.readonly, size_mib=None)
             for d in spec.disks
-            if d.role in {DiskRole.EXTRA, DiskRole.DATA}
+            if d.role is DiskRole.EXTRA
         ]
         resources.gpus = [HostGPU(pci_host=g.pci_host, supports_x_vga=g.supports_x_vga) for g in spec.gpus]
         return resources

src/aleph/vm/hypervisors/firecracker/microvm.py

@@ -87,6 +87,8 @@ class MicroVM:
     drives: list[Drive]
     init_timeout: float
     runtime_config: RuntimeConfiguration | None
+    # Raw bytes from the guest's ready signal; b"" until it arrives.
+    init_payload: bytes = b""
     mounted_rootfs: Path | None = None
     _unix_socket: Server | None = None
     enable_log: bool
@@ -142,6 +144,7 @@ def __init__(
         self.drives = []
         self.init_timeout = init_timeout
         self.runtime_config = None
+        self.init_payload = b""
         self.enable_log = enable_log
 
     def to_dict(self) -> dict:
@@ -393,13 +396,20 @@ def enable_drive(self, drive_path: Path, read_only: bool = True) -> Drive:
         self.drives.append(drive)
         return drive
 
-    async def wait_for_init(self) -> None:
-        """Wait for a connection from the init in the VM"""
+    async def wait_for_init(self, ready_port: int = 52) -> None:
+        """Wait for a connection from the init in the VM.
+
+        The raw bytes the guest sends with its ready signal are kept in
+        ``self.init_payload`` for pass-through consumers (the supervisor
+        contract reports them opaquely); the legacy RuntimeConfiguration parse
+        is preserved for the in-process program path.
+        """
         logger.debug("Waiting for init...")
         queue: asyncio.Queue[RuntimeConfiguration] = asyncio.Queue()
 
         async def unix_client_connected(reader: asyncio.StreamReader, _writer: asyncio.StreamWriter):
             data = await reader.read(1_000_000)
+            self.init_payload = data or b""
             if data:
                 config_dict: dict[str, Any] = msgpack.loads(data)
                 runtime_config = RuntimeConfiguration(version=config_dict["version"])
@@ -410,9 +420,11 @@ async def unix_client_connected(reader: asyncio.StreamReader, _writer: asyncio.S
             logger.debug("Runtime version: %s", runtime_config)
             await queue.put(runtime_config)
 
-        self._unix_socket = await asyncio.start_unix_server(unix_client_connected, path=f"{self.vsock_path}_52")
+        self._unix_socket = await asyncio.start_unix_server(
+            unix_client_connected, path=f"{self.vsock_path}_{ready_port}"
+        )
         if self.use_jailer:
-            system(f"chown jailman:jailman {self.vsock_path}_52")
+            system(f"chown jailman:jailman {self.vsock_path}_{ready_port}")
         try:
             self.runtime_config = await asyncio.wait_for(queue.get(), timeout=self.init_timeout)
             logger.debug("...signal from init received")

src/aleph/vm/orchestrator/views/__init__.py

@@ -202,16 +202,18 @@ async def debug_haproxy(request: web.Request) -> web.Response:
 
 
 def _vm_type_name(record: AgentVmRecord | None, info: VmInfo) -> str:
-    """vm_type label: from the agent's message when known, otherwise from the
-    supervisor's instance flag (spec-created / reattached VMs without a registry
-    record) — the same VmExecution.is_instance the old views fell back to.
-
-    The instance flag is used rather than the backend because the backend alone
-    cannot recover instance-ness: an instance running under Firecracker reports
-    Backend.FIRECRACKER yet is still an instance."""
+    """vm_type label: from the agent's message when known; otherwise a
+    best-effort guess from the guest channel (registry-miss fallback for
+    spec-created / reattached VMs).
+
+    The instance/program distinction is agent vocabulary the wire no longer
+    carries. Every VM the agent runs as a microvm has a guest channel and
+    instances have none, so the channel's presence recovers the label for VMs
+    we lost the record of. (Backend alone cannot: an instance running under
+    Firecracker reports Backend.FIRECRACKER yet is still an instance.)"""
     if record is not None:
         return VmType.from_message_content(record.message).name
-    return VmType.instance.name if info.is_instance else VmType.microvm.name
+    return VmType.microvm.name if info.guest_channel_path else VmType.instance.name
 
 
 def _datetime_from_ns(ns: int) -> datetime | None: