Add hypervisor.Backend abstraction layer

Introduce a pluggable hypervisor.Backend interface that decouples the
VM lifecycle from the libkrun runner implementation. The default
backend (hypervisor/libkrun) wraps the existing runner.Spawner and
runner.ProcessHandle behind the new Backend/VMHandle interfaces.

Breaking changes:
- Remove WithRunnerPath, WithLibDir, WithSpawner from propolis options
- Replace VM.PID() int with VM.ID() string
- Add WithBackend option accepting hypervisor.Backend

Security hardening:
- Validate PrepareRootFS return path stays within rootfs boundary
- pidFromID returns error on non-numeric, zero, or negative values
- Eliminate TOCTOU race in VM.Remove by always calling Stop
- Document VMHandle concurrency safety and idempotency contracts

Closes #1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: JAORMX

docs/MIGRATION-BACKEND-ABSTRACTION.md

@@ -0,0 +1,137 @@
+# Migration Guide: hypervisor.Backend Abstraction
+
+This document covers the breaking changes introduced by the
+`hypervisor.Backend` abstraction layer and how to migrate downstream
+consumers.
+
+## Breaking Changes
+
+| Removed API | Replacement | Affected projects |
+|---|---|---|
+| `propolis.WithRunnerPath(p)` | `libkrun.WithRunnerPath(p)` passed to `libkrun.NewBackend()` | waggle, apiary, toolhive-appliance |
+| `propolis.WithLibDir(d)` | `libkrun.WithLibDir(d)` passed to `libkrun.NewBackend()` | waggle, toolhive-appliance |
+| `propolis.WithSpawner(s)` | `libkrun.WithSpawner(s)` passed to `libkrun.NewBackend()` | tests only |
+| `propolis.VM.PID() int` | `propolis.VM.ID() string` | waggle, toolhive-appliance |
+
+## New Imports
+
+```go
+import "github.com/stacklok/propolis/hypervisor/libkrun"
+```
+
+## Migration Examples
+
+### waggle (`pkg/infra/vm/propolis.go`)
+
+**Before:**
+```go
+if opts.RunnerPath != "" {
+    propolisOpts = append(propolisOpts, propolis.WithRunnerPath(opts.RunnerPath))
+}
+if opts.LibDir != "" {
+    propolisOpts = append(propolisOpts, propolis.WithLibDir(opts.LibDir))
+}
+slog.Info("microVM created", "pid", vm.PID())
+```
+
+**After:**
+```go
+import "github.com/stacklok/propolis/hypervisor/libkrun"
+
+var backendOpts []libkrun.Option
+if opts.RunnerPath != "" {
+    backendOpts = append(backendOpts, libkrun.WithRunnerPath(opts.RunnerPath))
+}
+if opts.LibDir != "" {
+    backendOpts = append(backendOpts, libkrun.WithLibDir(opts.LibDir))
+}
+propolisOpts = append(propolisOpts, propolis.WithBackend(libkrun.NewBackend(backendOpts...)))
+slog.Info("microVM created", "id", vm.ID())
+```
+
+### apiary (`internal/infra/vm/runner.go`)
+
+**Before:**
+```go
+if r.runnerPath != "" {
+    opts = append(opts, propolis.WithRunnerPath(r.runnerPath))
+}
+```
+
+**After:**
+```go
+import "github.com/stacklok/propolis/hypervisor/libkrun"
+
+if r.runnerPath != "" {
+    opts = append(opts, propolis.WithBackend(libkrun.NewBackend(
+        libkrun.WithRunnerPath(r.runnerPath),
+    )))
+}
+```
+
+### toolhive-appliance (`internal/vm/libkrun/manager_cgo.go`)
+
+**Before:**
+```go
+if runnerPath != "" {
+    propolisOpts = append(propolisOpts, propolis.WithRunnerPath(runnerPath))
+}
+if libDir != "" {
+    propolisOpts = append(propolisOpts, propolis.WithLibDir(libDir))
+}
+PID: vmInstance.PID(),
+go m.reaperLoop(vmInstance.PID())
+```
+
+**After:**
+```go
+import (
+    "strconv"
+    "github.com/stacklok/propolis/hypervisor/libkrun"
+)
+
+var backendOpts []libkrun.Option
+if runnerPath != "" {
+    backendOpts = append(backendOpts, libkrun.WithRunnerPath(runnerPath))
+}
+if libDir != "" {
+    backendOpts = append(backendOpts, libkrun.WithLibDir(libDir))
+}
+propolisOpts = append(propolisOpts, propolis.WithBackend(libkrun.NewBackend(backendOpts...)))
+
+// For PID — parse ID string:
+id := vmInstance.ID()
+pid, _ := strconv.Atoi(id)
+// Use pid for state and reaper loop
+```
+
+### Test code using `WithSpawner`
+
+**Before:**
+```go
+spawner := &mockSpawner{proc: mockProc, err: nil}
+opts := []propolis.Option{
+    propolis.WithSpawner(spawner),
+}
+```
+
+**After:**
+```go
+// Implement hypervisor.Backend directly for test mocks:
+type mockBackend struct {
+    handle hypervisor.VMHandle
+    err    error
+}
+
+func (m *mockBackend) Name() string { return "mock" }
+func (m *mockBackend) PrepareRootFS(_ context.Context, p string, _ hypervisor.InitConfig) (string, error) {
+    return p, nil
+}
+func (m *mockBackend) Start(_ context.Context, _ hypervisor.VMConfig) (hypervisor.VMHandle, error) {
+    return m.handle, m.err
+}
+
+opts := []propolis.Option{
+    propolis.WithBackend(&mockBackend{handle: mockHandle}),
+}
+```

hypervisor/backend.go

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package hypervisor
+
+import "context"
+
+// Backend abstracts the hypervisor used to run a microVM.
+// Each implementation is responsible for preparing the root filesystem
+// and starting the VM through its own mechanism.
+type Backend interface {
+	// Name returns a short identifier for this backend (e.g. "libkrun").
+	Name() string
+	// PrepareRootFS applies any backend-specific setup to the rootfs
+	// directory (e.g. writing .krun_config.json for libkrun). It
+	// returns the path to use as the VM root filesystem, which must
+	// be equal to or within rootfsPath. Returning a path outside
+	// rootfsPath is a contract violation that callers will reject.
+	PrepareRootFS(ctx context.Context, rootfsPath string, initCfg InitConfig) (string, error)
+	// Start launches the VM and returns a handle for lifecycle management.
+	// If Start returns an error, the backend must have cleaned up any
+	// partial state (e.g. killed partially-spawned processes). Callers
+	// must not attempt recovery from partial start failures.
+	Start(ctx context.Context, cfg VMConfig) (VMHandle, error)
+}
+
+// VMHandle provides lifecycle control over a running VM.
+// All methods must be safe for concurrent use.
+type VMHandle interface {
+	// Stop gracefully shuts down the VM. Stop must be idempotent:
+	// calling it on an already-stopped VM returns nil.
+	Stop(ctx context.Context) error
+	// IsAlive reports whether the VM is still running.
+	IsAlive() bool
+	// ID returns a backend-specific identifier for the VM (e.g. PID
+	// for process-based backends, instance ID for cloud backends).
+	// The returned value must be stable across calls.
+	ID() string
+}
+
+// VMConfig contains all parameters needed to start a VM.
+type VMConfig struct {
+	Name             string
+	RootFSPath       string
+	NumVCPUs         uint32
+	RAMMiB           uint32
+	PortForwards     []PortForward
+	FilesystemMounts []FilesystemMount
+	InitConfig       InitConfig
+	DataDir          string
+	ConsoleLogPath   string
+	NetEndpoint      NetEndpoint
+}
+
+// InitConfig describes the process to run inside the VM.
+type InitConfig struct {
+	Cmd        []string
+	Env        []string
+	WorkingDir string
+}
+
+// NetEndpoint describes how the VM connects to the network.
+type NetEndpoint struct {
+	Type NetEndpointType
+	Path string
+}
+
+// NetEndpointType enumerates supported network transport mechanisms.
+type NetEndpointType int
+
+const (
+	// NetEndpointNone means no external network endpoint is configured.
+	NetEndpointNone NetEndpointType = iota
+	// NetEndpointUnixSocket connects via a Unix domain socket.
+	NetEndpointUnixSocket
+	// NetEndpointNamedPipe connects via a named pipe (Windows).
+	NetEndpointNamedPipe
+	// NetEndpointHVSocket connects via a Hyper-V socket.
+	NetEndpointHVSocket
+)
+
+// PortForward maps a host port to a guest port.
+type PortForward struct {
+	Host  uint16
+	Guest uint16
+}
+
+// FilesystemMount exposes a host directory to the guest.
+type FilesystemMount struct {
+	Tag      string
+	HostPath string
+}

hypervisor/doc.go

@@ -0,0 +1,7 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Package hypervisor defines the Backend interface for pluggable VM
+// hypervisor implementations. The default implementation is libkrun,
+// provided by the hypervisor/libkrun sub-package.
+package hypervisor

hypervisor/libkrun/backend.go

@@ -0,0 +1,110 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package libkrun
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+
+	"github.com/stacklok/propolis/hypervisor"
+	"github.com/stacklok/propolis/image"
+	"github.com/stacklok/propolis/runner"
+)
+
+// Option configures a libkrun Backend.
+type Option func(*Backend)
+
+// WithRunnerPath sets the path to the propolis-runner binary.
+// When empty, the runner is found via $PATH or alongside the calling binary.
+func WithRunnerPath(p string) Option { return func(b *Backend) { b.runnerPath = p } }
+
+// WithLibDir sets the path to a directory containing libkrun/libkrunfw
+// shared libraries. The runner subprocess will use this via LD_LIBRARY_PATH.
+func WithLibDir(d string) Option { return func(b *Backend) { b.libDir = d } }
+
+// WithSpawner sets a custom spawner for the runner subprocess.
+// When nil (default), the standard runner.DefaultSpawner is used.
+func WithSpawner(s runner.Spawner) Option { return func(b *Backend) { b.spawner = s } }
+
+// Backend implements hypervisor.Backend using libkrun.
+type Backend struct {
+	runnerPath string
+	libDir     string
+	spawner    runner.Spawner
+}
+
+// NewBackend creates a libkrun backend with the given options.
+func NewBackend(opts ...Option) *Backend {
+	b := &Backend{}
+	for _, o := range opts {
+		o(b)
+	}
+	return b
+}
+
+// Name returns "libkrun".
+func (b *Backend) Name() string { return "libkrun" }
+
+// PrepareRootFS writes .krun_config.json into the rootfs directory.
+func (b *Backend) PrepareRootFS(_ context.Context, rootfsPath string, initCfg hypervisor.InitConfig) (string, error) {
+	kc := image.KrunConfig{
+		Cmd:        initCfg.Cmd,
+		Env:        initCfg.Env,
+		WorkingDir: initCfg.WorkingDir,
+	}
+	if err := kc.WriteTo(rootfsPath); err != nil {
+		return "", fmt.Errorf("write krun config: %w", err)
+	}
+	return rootfsPath, nil
+}
+
+// Start launches the VM via the propolis-runner subprocess.
+func (b *Backend) Start(ctx context.Context, cfg hypervisor.VMConfig) (hypervisor.VMHandle, error) {
+	var netSocket string
+	if cfg.NetEndpoint.Type == hypervisor.NetEndpointUnixSocket {
+		netSocket = cfg.NetEndpoint.Path
+	}
+
+	runCfg := runner.Config{
+		RootPath:     cfg.RootFSPath,
+		NumVCPUs:     cfg.NumVCPUs,
+		RAMMiB:       cfg.RAMMiB,
+		NetSocket:    netSocket,
+		PortForwards: toRunnerPortForwards(cfg.PortForwards),
+		VirtioFS:     toRunnerVirtioFS(cfg.FilesystemMounts),
+		ConsoleLog:   cfg.ConsoleLogPath,
+		LibDir:       b.libDir,
+		RunnerPath:   b.runnerPath,
+		VMLogPath:    filepath.Join(cfg.DataDir, "vm.log"),
+	}
+
+	spawner := b.spawner
+	if spawner == nil {
+		spawner = runner.DefaultSpawner{}
+	}
+
+	proc, err := spawner.Spawn(ctx, runCfg)
+	if err != nil {
+		return nil, fmt.Errorf("spawn runner: %w", err)
+	}
+
+	return &processHandle{proc: proc}, nil
+}
+
+func toRunnerPortForwards(ports []hypervisor.PortForward) []runner.PortForward {
+	out := make([]runner.PortForward, len(ports))
+	for i, p := range ports {
+		out[i] = runner.PortForward{Host: p.Host, Guest: p.Guest}
+	}
+	return out
+}
+
+func toRunnerVirtioFS(mounts []hypervisor.FilesystemMount) []runner.VirtioFSMount {
+	out := make([]runner.VirtioFSMount, len(mounts))
+	for i, m := range mounts {
+		out[i] = runner.VirtioFSMount{Tag: m.Tag, HostPath: m.HostPath}
+	}
+	return out
+}