Add gn-ten node lab topology boot plan

Author: nshkrdotcom

support/gn_ten_node_lab/README.md

@@ -12,11 +12,26 @@ It owns local test-harness mechanics:
 - peer node lifecycle;
 - code-path sync in dev peer mode;
 - bounded `:erpc` admin/proof calls;
+- checked-in topology fixture loading;
+- required app boot probes;
+- owner-defined facade host and `:pg` readiness checks;
 - node cleanup receipts.
 
 It does not own AppKit, Mezzanine, Citadel, OuterBrain, Jido Integration,
 Execution Plane, AITrace, TRINITY, GEPA, or product business semantics.
 
+## Topology Fixtures
+
+Temporary v2 topology fixtures live under `priv/topologies/` until
+`examples/gn_ten_distributed_stack` exists:
+
+- `control_3_node.exs`
+- `context_6_node.exs`
+
+These fixtures name owner facade modules and owner-defined `:pg` groups. The
+node lab can host those modules on peer nodes for readiness proof, but StackLab
+does not define the domain contract.
+
 ## Security Posture
 
 Default Erlang distribution cookies are local development cluster authority,

support/gn_ten_node_lab/lib/gn_ten_node_lab_fixture/remote_facade.ex

@@ -0,0 +1,5 @@
+defmodule GnTenNodeLabFixture.RemoteFacade do
+  @moduledoc false
+
+  def owner_group, do: {__MODULE__, :fixture}
+end

support/gn_ten_node_lab/lib/stack_lab/gn_ten_node_lab.ex

@@ -7,14 +7,23 @@ defmodule StackLab.GnTenNodeLab do
   evidence semantics remain in their owner repos.
   """
 
-  alias StackLab.GnTenNodeLab.{Peer, Preflight, Topology}
+  alias StackLab.GnTenNodeLab.{BootPlan, Peer, Preflight, Topology}
 
   @spec preflight(keyword()) :: {:ok, map()} | {:error, map()}
   defdelegate preflight(opts \\ []), to: Preflight, as: :run
 
   @spec validate_topology(map()) :: {:ok, Topology.t()} | {:error, [map()]}
   defdelegate validate_topology(spec), to: Topology, as: :validate
 
+  @spec load_topology(Path.t()) :: {:ok, Topology.t()} | {:error, [map()]}
+  defdelegate load_topology(path), to: Topology, as: :load_file
+
+  @spec topology_instances(Topology.t()) :: [map()]
+  defdelegate topology_instances(topology), to: BootPlan, as: :instances
+
+  @spec boot_instance(Peer.t() | node(), map(), keyword()) :: {:ok, map()} | {:error, map()}
+  defdelegate boot_instance(target, instance, opts \\ []), to: BootPlan
+
   @spec with_peer((Peer.t() -> term()), keyword()) :: {:ok, term()} | {:error, map()}
   defdelegate with_peer(fun, opts \\ []), to: Peer
 end

support/gn_ten_node_lab/lib/stack_lab/gn_ten_node_lab/boot_plan.ex

@@ -0,0 +1,152 @@
+defmodule StackLab.GnTenNodeLab.BootPlan do
+  @moduledoc """
+  Peer-node app boot and owner-facade readiness probes for topology instances.
+  """
+
+  alias StackLab.GnTenNodeLab.{FacadeHost, Peer, Topology}
+
+  @remote_call_timeout_ms 5_000
+
+  @spec instances(Topology.t()) :: [map()]
+  def instances(%Topology{} = topology), do: Topology.instance_specs(topology)
+
+  @spec boot_instance(Peer.t() | node(), map(), keyword()) :: {:ok, map()} | {:error, map()}
+  def boot_instance(target, instance, opts \\ []) when is_map(instance) and is_list(opts) do
+    node = target_node(target)
+
+    with {:ok, started_apps} <- start_required_apps(node, Map.get(instance, :required_apps, [])),
+         {:ok, facade_hosts} <-
+           maybe_start_facade_hosts(node, Map.get(instance, :owner_groups, []), opts),
+         {:ok, owner_group_membership} <-
+           probe_owner_groups(node, Map.get(instance, :owner_groups, [])) do
+      {:ok,
+       %{
+         "node_id" => Map.fetch!(instance, :node_id),
+         "profile" => instance.profile |> Atom.to_string(),
+         "node" => Atom.to_string(node),
+         "started_apps" => started_apps,
+         "facade_hosts" => facade_hosts,
+         "owner_group_membership" => owner_group_membership,
+         "ready?" => true
+       }}
+    end
+  end
+
+  @spec probe_owner_groups(Peer.t() | node(), [tuple()]) :: {:ok, [map()]} | {:error, map()}
+  def probe_owner_groups(target, owner_groups) when is_list(owner_groups) do
+    node = target_node(target)
+
+    owner_groups
+    |> Enum.reduce_while({:ok, []}, fn owner_group, {:ok, receipts} ->
+      case owner_group_members(node, owner_group) do
+        {:ok, members} when members != [] ->
+          {:cont, {:ok, [membership_receipt(owner_group, members) | receipts]}}
+
+        {:ok, []} ->
+          {:halt,
+           {:error, failure("owner_group_not_registered", owner_group: inspect(owner_group))}}
+
+        {:error, reason} ->
+          {:halt, {:error, failure("owner_group_probe_failed", reason: inspect(reason))}}
+      end
+    end)
+    |> case do
+      {:ok, receipts} -> {:ok, Enum.reverse(receipts)}
+      {:error, failure} -> {:error, failure}
+    end
+  end
+
+  defp maybe_start_facade_hosts(_node, _owner_groups, start_facade_hosts?: false), do: {:ok, []}
+
+  defp maybe_start_facade_hosts(node, owner_groups, _opts) do
+    owner_groups
+    |> Enum.reduce_while({:ok, []}, fn owner_group, {:ok, receipts} ->
+      case start_facade_host(node, owner_group) do
+        {:ok, receipt} -> {:cont, {:ok, [receipt | receipts]}}
+        {:error, failure} -> {:halt, {:error, failure}}
+      end
+    end)
+    |> case do
+      {:ok, receipts} -> {:ok, Enum.reverse(receipts)}
+      {:error, failure} -> {:error, failure}
+    end
+  end
+
+  defp start_required_apps(node, required_apps) do
+    required_apps
+    |> Enum.reduce_while({:ok, []}, fn app, {:ok, receipts} ->
+      case Peer.remote_call(
+             node,
+             Application,
+             :ensure_all_started,
+             [app],
+             @remote_call_timeout_ms
+           ) do
+        {:ok, {:ok, apps}} ->
+          {:cont,
+           {:ok, [%{"app" => Atom.to_string(app), "started" => apps_to_strings(apps)} | receipts]}}
+
+        {:ok, {:error, reason}} ->
+          {:halt,
+           {:error,
+            failure("app_start_failed", app: Atom.to_string(app), reason: inspect(reason))}}
+
+        {:error, reason} ->
+          {:halt,
+           {:error,
+            failure("app_start_probe_failed", app: Atom.to_string(app), reason: inspect(reason))}}
+      end
+    end)
+    |> case do
+      {:ok, receipts} -> {:ok, Enum.reverse(receipts)}
+      {:error, failure} -> {:error, failure}
+    end
+  end
+
+  defp start_facade_host(node, {facade_module, _name} = owner_group) do
+    args = [[facade_module: facade_module, owner_group: owner_group]]
+
+    case Peer.remote_call(node, FacadeHost, :start, args, @remote_call_timeout_ms) do
+      {:ok, {:ok, pid}} ->
+        {:ok,
+         %{
+           "facade_module" => inspect(facade_module),
+           "owner_group" => inspect(owner_group),
+           "pid" => inspect(pid)
+         }}
+
+      {:ok, {:error, reason}} ->
+        {:error,
+         failure("facade_host_start_failed",
+           owner_group: inspect(owner_group),
+           reason: inspect(reason)
+         )}
+
+      {:error, reason} ->
+        {:error,
+         failure("facade_host_start_probe_failed",
+           owner_group: inspect(owner_group),
+           reason: inspect(reason)
+         )}
+    end
+  end
+
+  defp owner_group_members(node, owner_group) do
+    Peer.remote_call(node, :pg, :get_members, [owner_group], @remote_call_timeout_ms)
+  end
+
+  defp target_node(%Peer{peer_node: peer_node}), do: peer_node
+  defp target_node(node) when is_atom(node), do: node
+
+  defp membership_receipt(owner_group, members) do
+    %{
+      "owner_group" => inspect(owner_group),
+      "member_count" => length(members),
+      "members" => Enum.map(members, &inspect/1)
+    }
+  end
+
+  defp apps_to_strings(apps), do: Enum.map(apps, &Atom.to_string/1)
+
+  defp failure(code, attrs), do: Enum.into(attrs, %{code: code})
+end

support/gn_ten_node_lab/lib/stack_lab/gn_ten_node_lab/facade_host.ex

@@ -0,0 +1,76 @@
+defmodule StackLab.GnTenNodeLab.FacadeHost do
+  @moduledoc """
+  Generic test-harness process that exposes an owner facade module through
+  the owner-defined `:pg` group for local distributed proofs.
+
+  This process is StackLab-owned harness infrastructure. It does not define the
+  facade contract and it does not move owner semantics into StackLab.
+  """
+
+  use GenServer
+
+  @spec start_link(keyword()) :: GenServer.on_start()
+  def start_link(opts) when is_list(opts) do
+    GenServer.start_link(__MODULE__, opts)
+  end
+
+  @spec start(keyword()) :: GenServer.on_start()
+  def start(opts) when is_list(opts) do
+    GenServer.start(__MODULE__, opts)
+  end
+
+  @impl true
+  def init(opts) do
+    facade_module = Keyword.fetch!(opts, :facade_module)
+    owner_group = Keyword.fetch!(opts, :owner_group)
+
+    with :ok <- ensure_facade_module(facade_module),
+         :ok <- ensure_owner_group(facade_module, owner_group),
+         :ok <- ensure_pg_started(),
+         :ok <- join_owner_group(owner_group) do
+      {:ok, %{facade_module: facade_module, owner_group: owner_group}}
+    else
+      {:error, reason} -> {:stop, reason}
+    end
+  end
+
+  defp ensure_facade_module(facade_module) when is_atom(facade_module) do
+    with {:module, ^facade_module} <- Code.ensure_loaded(facade_module),
+         true <- function_exported?(facade_module, :owner_group, 0) do
+      :ok
+    else
+      _other -> {:error, {:facade_module_unavailable, facade_module}}
+    end
+  end
+
+  defp ensure_facade_module(facade_module), do: {:error, {:invalid_facade_module, facade_module}}
+
+  defp ensure_owner_group(facade_module, owner_group) do
+    if facade_module.owner_group() == owner_group do
+      :ok
+    else
+      {:error, {:owner_group_mismatch, facade_module, owner_group}}
+    end
+  end
+
+  defp ensure_pg_started do
+    case Process.whereis(:pg) do
+      nil ->
+        case :pg.start_link() do
+          {:ok, _pid} -> :ok
+          {:error, {:already_started, _pid}} -> :ok
+          {:error, reason} -> {:error, {:pg_start_failed, reason}}
+        end
+
+      _pid ->
+        :ok
+    end
+  end
+
+  defp join_owner_group(owner_group) do
+    case :pg.join(owner_group, self()) do
+      :ok -> :ok
+      {:error, reason} -> {:error, {:owner_group_join_failed, reason}}
+    end
+  end
+end