docs(reaper): correct liveness-source count; note intentional create_mutable/2 refusal and liveness test scope

Author: markovejnovic

lib/hyper/node/img.ex

@@ -61,6 +61,9 @@ defmodule Hyper.Node.Img do
   @doc "Create a per-VM mutable layer for `vm_id` over `img_id`."
   @spec create_mutable(Hyper.Img.id(), Hyper.Vm.Id.t()) :: {:ok, pid()} | {:error, term()}
   def create_mutable(img_id, vm_id) do
+    # Unlike activate/1, we intentionally do NOT map {:already_started, pid} -> {:ok, pid}:
+    # vm_ids are unique per VM, so a duplicate vm_id is a bug, not a shared-server reuse.
+    # Surfacing {:error, {:already_started, pid}} enforces the one-mutable-per-vm invariant.
     case DynamicSupervisor.start_child(
            @mutable_sup,
            {Mutable, %Mutable.Opts{img_id: img_id, vm_id: vm_id}}

lib/hyper/node/reaper.ex

@@ -6,10 +6,12 @@ defmodule Hyper.Node.Reaper do
   whose vm_id never reboots (so `Hyper.Node.Reclaim`, which runs once at boot, and
   the relaunch-time cleanup in the FireVMM path, never get a chance to clear it).
 
-  Liveness is the whole point. The reaper consults two independent sources of
-  truth for "this vm is alive" (`Plan.orphans/3` removes their union from the
-  candidate set) and only ever touches `hyper-rw-*` dm names and per-VM cgroup
-  leaves - never `hyper-thinpool`, `hyper-img-*`, or a live VM's resources. A
+  Liveness is the whole point. The reaper consults three independent sources of
+  truth for "this vm is alive" — the local VM supervisor's children, the cluster
+  routing table, and the node's live mutable layers (`Img.Mutable.active_vm_ids/0`)
+  — (`Plan.orphans/3` removes their union from the candidate set) and only ever
+  touches `hyper-rw-*` dm names and per-VM cgroup leaves - never `hyper-thinpool`,
+  `hyper-img-*`, or a live VM's resources. A
   candidate must also survive two consecutive ticks (`Plan.confirm/2`) before it
   is reaped, so a VM caught mid-boot (resources present, not yet registered) is
   given a grace tick rather than destroyed.

test/hyper/node/reaper/liveness_test.exs

@@ -1,4 +1,7 @@
 defmodule Hyper.Node.Reaper.LivenessTest do
+  # Guards the Img.Mutable.active_vm_ids/0 + Plan.orphans/3 contract: a live mutable
+  # layer protects its vm_id from reaping. The gather_live/0 union of this source into
+  # the full live set is verified by manual live-node testing (Task 4), not CI.
   use ExUnit.Case, async: false
 
   alias Hyper.Node.Img