// Package daemon hosts the Banger owner-daemon process.
//
// The daemon exposes a JSON-RPC endpoint over a Unix socket. The
// *Daemon type is a thin composition root: it holds shared
// infrastructure (store, runner, logger, layout, config, listener,
// privileged-ops adapter) plus pointers to four focused services and
// forwards RPCs to them.
//
// On the supported systemd install path, this package runs inside
// `bangerd.service` as the configured owner user and delegates
// privileged host-kernel operations to `bangerd-root.service` through
// the privileged-ops seam. Non-system/dev paths use the same seam with
// an in-process adapter instead.
//
// Services:
//
//	*HostNetwork      Bridge / tap pool / NAT / DNS / firecracker
//	                  process / DM snapshots / vsock readiness.
//	                  Owns tapPool and vmDNS.
//	*ImageService     Register / promote / delete / pull (bundle +
//	                  OCI) / kernel catalog / managed-seed refresh.
//	                  Owns imageOpsMu.
//	*WorkspaceService workspace.prepare / workspace.export + the
//	                  per-VM authorised-key and git-identity sync
//	                  that runs at start. Owns workspaceLocks.
//	*VMService        VM lifecycle (create/start/stop/restart/kill/
//	                  delete/set), stats, ports, preflight. Owns
//	                  vmLocks, createVMMu, createOps, handles.
//
// Subpackages (stateless helpers):
//
//	internal/daemon/opstate    Generic Registry[T AsyncOp].
//	internal/daemon/dmsnap     Device-mapper COW snapshot lifecycle.
//	internal/daemon/fcproc     Firecracker process helpers.
//	internal/daemon/imagemgr   Image subsystem helpers.
//	internal/daemon/workspace  Workspace helpers.
//
// File inventory:
//
//	daemon.go            Composition root, Open/Close/Serve, dispatch,
//	                     reconcile orchestrator, backgroundLoop.
//	host_network.go      HostNetwork struct + constructor.
//	image_service.go     ImageService struct + constructor + FindImage.
//	workspace_service.go WorkspaceService struct + constructor.
//	vm_service.go        VMService struct + constructor + FindVM,
//	                     TouchVM, withVMLock* family, lockVMID.
//
//	nat.go, dns_routing.go, tap_pool.go, snapshot.go   HostNetwork methods.
//	images.go, images_pull.go, image_seed.go, kernels.go   ImageService methods.
//	workspace.go, vm_authsync.go                       WorkspaceService methods.
//	vm_lifecycle.go, vm_create.go, vm_create_ops.go,
//	vm_stats.go, vm_set.go, vm_disk.go, vm_handles.go,
//	ports.go, preflight.go                             VMService methods.
//
//	vm.go                Cross-service constants, rebuildDNS /
//	                     cleanupRuntime / generateName (*VMService),
//	                     and small stateless utilities.
//	capabilities.go      Pluggable capability hooks executed at VM
//	                     start. Each capability is a plain struct
//	                     with explicit service-pointer fields
//	                     (workDiskCapability carries vm+ws+store,
//	                     dnsCapability carries net, natCapability
//	                     carries vm+net+logger). wireServices builds
//	                     the default list; VMService invokes hooks
//	                     through a capabilityHooks seam. No hook
//	                     reaches back to *Daemon.
//	vm_locks.go          vmLockSet primitive.
//	guest_ssh.go         guestSSHClient, dialGuest, waitForGuestSSH.
//	ssh_client_config.go Daemon-managed SSH client key material.
//	doctor.go            Host diagnostics.
//	logger.go            slog configuration.
//	runtime_assets.go    Companion-binary paths.
//
// Lock ordering:
//
//	VMService.vmLocks[id]  →  WorkspaceService.workspaceLocks[id]
//	                       →  {VMService.createVMMu, ImageService.imageOpsMu}
//	                       →  subsystem-local locks
//
// vmLocks[id] and workspaceLocks[id] are NEVER held at the same
// time. workspace.prepare acquires vmLocks[id] only long enough to
// validate VM state, releases it, then acquires workspaceLocks[id]
// for the slow guest I/O phase. Lifecycle ops (start/stop/delete/
// set) hold vmLocks[id] across the whole flow. Subsystem-local
// locks (tapPool.mu, opstate.Registry mu, handleCache.mu) are
// leaves. See ARCHITECTURE.md for details.
package daemon
