controller

type ApplyResult struct {
	Resources []ResourceResult
}

type BootstrapReport struct {
	RunPath string

	KukeonCgroupExistsPre  bool
	KukeonCgroupExistsPost bool
	KukeonCgroupCreated    bool

	// CNI bootstrap details
	CniConfigDir           string
	CniCacheDir            string
	CniBinDir              string
	CniConfigDirExistsPre  bool
	CniCacheDirExistsPre   bool
	CniBinDirExistsPre     bool
	CniConfigDirCreated    bool
	CniCacheDirCreated     bool
	CniBinDirCreated       bool
	CniConfigDirExistsPost bool
	CniCacheDirExistsPost  bool
	CniBinDirExistsPost    bool

	// Default user hierarchy (realm=default, space=default, stack=default, no cell).
	DefaultRealm RealmSection
	DefaultSpace SpaceSection
	DefaultStack StackSection

	// System hierarchy (realm=kuke-system, space=kukeon, stack=kukeon, cell=kukeond).
	SystemRealm RealmSection
	SystemSpace SpaceSection
	SystemStack StackSection
	SystemCell  CellSection

	// KukeondImage is the resolved image reference provisioned for the kukeond
	// container inside the system cell.
	KukeondImage string
}

type BuildCachePurgeOutcome struct {
	Namespace string
	Path      string
	Existed   bool
	Removed   bool
	Err       error
}

type CellSection struct {
	CellName                    string
	CellMetadataExistsPre       bool
	CellMetadataExistsPost      bool
	CellCreated                 bool
	CellCgroupExistsPre         bool
	CellCgroupExistsPost        bool
	CellCgroupCreated           bool
	CellRootContainerExistsPre  bool
	CellRootContainerExistsPost bool
	CellRootContainerCreated    bool
	CellStartedPre              bool
	CellStartedPost             bool
	CellStarted                 bool
	// CellRecreatedDueToImageDrift is true when bootstrapCell observed a
	// persisted cell whose root container image diverged from the desired
	// image and dropped into a stop+delete+recreate branch instead of the
	// idempotent EnsureCell+StartCell path. Issue #868: without this branch,
	// `kuke init --kukeond-image <new>` would silently keep starting the
	// stale container record left behind by a prior reset, and the running
	// daemon binary would never refresh across a `make dev-init` re-bootstrap.
	CellRecreatedDueToImageDrift bool
	// CellPriorImage carries the persisted root container image observed at
	// drift detection time, so the init report can render
	// "recreated (image drift: <old> → <new>)" instead of the misleading
	// "already existed" line on the recreate branch.
	CellPriorImage string
}

type ContainerCreationOutcome struct {
	Name       string
	ExistsPre  bool
	ExistsPost bool
	Created    bool
}

type Controller interface {
	Bootstrap() (BootstrapReport, error)
	CreateRealm(realm intmodel.Realm) (CreateRealmResult, error)
	CreateSpace(space intmodel.Space) (CreateSpaceResult, error)
	CreateStack(stack intmodel.Stack) (CreateStackResult, error)
	CreateCell(cell intmodel.Cell) (CreateCellResult, error)
	CreateSecret(secret intmodel.Secret) (CreateSecretResult, error)
	DeleteRealm(realm intmodel.Realm, force, cascade bool) (DeleteRealmResult, error)
	DeleteSpace(space intmodel.Space, force, cascade bool) (DeleteSpaceResult, error)
	DeleteStack(stack intmodel.Stack, force, cascade bool) (DeleteStackResult, error)
	DeleteCell(cell intmodel.Cell) (DeleteCellResult, error)
	GetRealm(realm intmodel.Realm) (GetRealmResult, error)
	ListRealms() ([]intmodel.Realm, error)
	GetSpace(space intmodel.Space) (GetSpaceResult, error)
	ListSpaces(realmName string) ([]intmodel.Space, error)
	GetStack(stack intmodel.Stack) (GetStackResult, error)
	ListStacks(realmName, spaceName string) ([]intmodel.Stack, error)
	GetCell(cell intmodel.Cell) (GetCellResult, error)
	ListCells(realmName, spaceName, stackName string) ([]intmodel.Cell, error)
	GetContainer(container intmodel.Container) (GetContainerResult, error)
	ListContainers(realmName, spaceName, stackName, cellName string) ([]intmodel.ContainerSpec, error)
	StartCell(cell intmodel.Cell) (StartCellResult, error)
	StopCell(cell intmodel.Cell) (StopCellResult, error)
	KillCell(cell intmodel.Cell) (KillCellResult, error)
	PurgeRealm(realm intmodel.Realm, force, cascade bool) (PurgeRealmResult, error)
	PurgeSpace(space intmodel.Space, force, cascade bool) (PurgeSpaceResult, error)
	PurgeStack(stack intmodel.Stack, force, cascade bool) (PurgeStackResult, error)
	PurgeCell(cell intmodel.Cell, force, cascade bool) (PurgeCellResult, error)
	RefreshAll() (RefreshResult, error)
	ReconcileCells() (ReconcileResult, error)
	Uninstall(opts UninstallOptions) (UninstallReport, error)
	Close() error
}

type CreateCellResult struct {
	Cell intmodel.Cell

	MetadataExistsPre       bool
	MetadataExistsPost      bool
	CgroupExistsPre         bool
	CgroupExistsPost        bool
	CgroupCreated           bool
	RootContainerExistsPre  bool
	RootContainerExistsPost bool
	RootContainerCreated    bool
	StartedPre              bool
	StartedPost             bool
	Started                 bool
	Created                 bool

	Containers []ContainerCreationOutcome
}

type CreateConfigResult struct {
	Config  intmodel.CellConfig
	Created bool
}

type CreateRealmResult struct {
	Realm intmodel.Realm

	MetadataExistsPre             bool
	MetadataExistsPost            bool
	CgroupExistsPre               bool
	CgroupExistsPost              bool
	CgroupCreated                 bool
	ContainerdNamespaceExistsPre  bool
	ContainerdNamespaceExistsPost bool
	ContainerdNamespaceCreated    bool
	Created                       bool
}

type CreateSecretResult struct {
	Secret  intmodel.Secret
	Created bool
}

type CreateSpaceResult struct {
	Space intmodel.Space

	MetadataExistsPre    bool
	MetadataExistsPost   bool
	CgroupExistsPre      bool
	CgroupExistsPost     bool
	CgroupCreated        bool
	CNINetworkExistsPre  bool
	CNINetworkExistsPost bool
	CNINetworkCreated    bool
	Created              bool
}

type CreateStackResult struct {
	Stack intmodel.Stack

	MetadataExistsPre  bool
	MetadataExistsPost bool
	CgroupExistsPre    bool
	CgroupExistsPost   bool
	CgroupCreated      bool
	Created            bool
}

type DaemonStopReport struct {
	PIDFilePresent bool
	PIDFile        string
	PID            int
	Signalled      bool
	ForceKilled    bool
}

type DaemonStopper func(ctx context.Context, pidFile string, gracePeriod time.Duration) (DaemonStopReport, error)

type DeleteBlueprintResult struct {
	Blueprint intmodel.CellBlueprint
	Deleted   bool
}

type DeleteCellResult struct {
	Cell              intmodel.Cell
	ContainersDeleted bool
	CgroupDeleted     bool
	MetadataDeleted   bool
}

type DeleteConfigResult struct {
	Config       intmodel.CellConfig
	Deleted      bool
	BackRefCells []string
}

type DeleteImageResult struct {
	Realm     string
	Namespace string
	Ref       string
}

type DeleteRealmResult struct {
	Realm                      intmodel.Realm
	Deleted                    []string // Resources that were deleted (metadata, cgroup, namespace, cascaded resources)
	MetadataDeleted            bool
	CgroupDeleted              bool
	ContainerdNamespaceDeleted bool
}

type DeleteResult struct {
	Resources []ResourceDeleteResult
}

type DeleteSecretResult struct {
	Secret  intmodel.Secret
	Deleted bool
}

type DeleteSpaceResult struct {
	SpaceName string
	RealmName string
	Space     intmodel.Space

	MetadataDeleted   bool
	CgroupDeleted     bool
	CNINetworkDeleted bool

	Deleted []string // Resources that were deleted (metadata, cgroup, network, cascaded resources)
}

type DeleteStackResult struct {
	StackName string
	RealmName string
	SpaceName string
	Stack     intmodel.Stack

	MetadataDeleted bool
	CgroupDeleted   bool

	Deleted []string // Resources that were deleted (metadata, cgroup, cascaded resources)
}

type Exec struct {
	// contains filtered or unexported fields
}

type GetBlueprintResult struct {
	Blueprint      intmodel.CellBlueprint
	MetadataExists bool
}

type GetCellResult struct {
	Cell                intmodel.Cell
	MetadataExists      bool
	CgroupExists        bool
	RootContainerExists bool
	// RootContainerTaskRunning reports whether the cell's root container has a
	// live containerd task (status Running). RootContainerExists keys on the
	// containerd container *record*, which survives a host/daemon restart while
	// the backing task does not (#654, #683): a record-existence check passes
	// even when attaching would land on a dead socket. Callers gating an attach
	// must consult this task-liveness signal, not record existence.
	RootContainerTaskRunning bool
}

type GetConfigResult struct {
	Config         intmodel.CellConfig
	MetadataExists bool
}

type GetContainerResult struct {
	Container          intmodel.Container
	CellMetadataExists bool
	ContainerExists    bool
}

type GetImageResult struct {
	Realm     string
	Namespace string
	Image     ImageInfo
}

type GetRealmResult struct {
	Realm                     intmodel.Realm
	MetadataExists            bool
	CgroupExists              bool
	ContainerdNamespaceExists bool
}

type GetSecretResult struct {
	Secret         intmodel.Secret
	MetadataExists bool
}

type GetSpaceResult struct {
	Space            intmodel.Space
	MetadataExists   bool
	CgroupExists     bool
	CNINetworkExists bool
}

type GetStackResult struct {
	Stack          intmodel.Stack
	MetadataExists bool
	CgroupExists   bool
}

type ImageInfo struct {
	Name      string
	Size      int64
	CreatedAt time.Time
	Digest    string
	MediaType string
	Labels    map[string]string
}

type KillCellResult struct {
	Cell   intmodel.Cell
	Killed bool
}

type ListImagesResult struct {
	Realm     string
	Namespace string
	Images    []ImageInfo
}

type LoadImageResult struct {
	Realm     string
	Namespace string
	Images    []string
}

type MountReleaseAttempt struct {
	Target   string
	Released bool
	Err      error
}

type MountReleaser func(root string) ([]MountReleaseAttempt, error)

type Options struct {
	RunPath          string
	ContainerdSocket string
	// KukeondImage is the container image for the kukeond system cell. If empty,
	// bootstrap will skip provisioning the system cell (but still provision the
	// system realm/space/stack).
	KukeondImage string
	// KukeondSocket is the unix socket path kukeond serves on. Used by bootstrap
	// to build the bind-mount for the system cell.
	KukeondSocket string
	// KukeondSocketGID, when non-zero, is passed to the kukeond cell as
	// --socket-gid <gid> so the daemon can chown its listener socket on every
	// restart. Set by `kuke init` to the kukeon group's numeric GID.
	KukeondSocketGID int
	// KukeondConfiguration, when set, is passed to the kukeond cell as
	// --configuration <path> and bind-mounted into the cell so the daemon
	// re-reads the same ServerConfiguration on every restart.
	KukeondConfiguration string
	// ForceRegenerateCNI forces bootstrap to rewrite space conflists even when
	// they already exist with the expected bridge name. Surfaces via
	// `kuke init --force-regenerate-cni`.
	ForceRegenerateCNI bool
	// DefaultMemoryLimitBytes, when > 0, is the daemon-wide fallback memory
	// limit (in bytes) applied to every admitted container whose
	// ContainerSpec.Resources.MemoryLimitBytes is unset or zero. Surfaces via
	// `kukeond serve --default-memory-limit-bytes`, KUKEOND_DEFAULT_MEMORY_LIMIT_BYTES,
	// or ServerConfiguration.Spec.DefaultMemoryLimitBytes. Closes the host-
	// wedge gap on no-swap + no-userspace-OOM hosts (issue #531). Zero (the
	// default) preserves the prior behavior — no fallback, the kernel sees
	// memory.max=max for any spec that did not declare a limit.
	DefaultMemoryLimitBytes int64
	// KukettyLogLevel is the daemon-wide default verbosity of the kuketty
	// wrapper's slog output, applied when a cell omits per-container
	// ContainerTty.LogLevel. Surfaces via `kukeond serve --kuketty-log-level`,
	// KUKEOND_KUKETTY_LOG_LEVEL, or ServerConfiguration.Spec.KukettyLogLevel.
	// Empty falls through to the hardcoded "info" default inside the renderer.
	// Issue #599.
	KukettyLogLevel string
	// DiskPressureWarnPercent, when > 0, is the data-volume usage percentage
	// above which the reconcile loop emits a rate-limited WARN naming the realm
	// and current usage (no deletion). Surfaces via
	// `kukeond serve --disk-pressure-warn-percent` / KUKEOND_DISK_PRESSURE_WARN_PCT.
	// Zero disables the warning. Issue #1035.
	DiskPressureWarnPercent int
	// DiskPressureBlockPercent, when > 0, is the data-volume usage percentage
	// at or above which CreateCell refuses to provision a new cell. Surfaces
	// via `kukeond serve --disk-pressure-block-percent` /
	// KUKEOND_DISK_PRESSURE_BLOCK_PCT. Zero disables the guard. Issue #1035.
	DiskPressureBlockPercent int
}

type PruneImagesResult struct {
	Realm          string
	Namespace      string
	LeasesDeleted  int
	LeasesRetained int
}

type PurgeCellResult struct {
	Cell              intmodel.Cell
	ContainersDeleted bool
	CgroupDeleted     bool
	MetadataDeleted   bool
	PurgeSucceeded    bool
	Force             bool
	Cascade           bool
	Deleted           []string // Resources that were deleted (standard cleanup)
	Purged            []string // Additional resources purged (CNI, orphaned containers, etc.)
}

type PurgeRealmResult struct {
	Realm            intmodel.Realm
	RealmDeleted     bool     // Whether realm deletion succeeded
	PurgeSucceeded   bool     // Whether comprehensive purge succeeded
	NamespaceRemoved bool     // Whether the containerd namespace was actually removed
	Force            bool     // Force flag that was used
	Cascade          bool     // Cascade flag that was used
	Deleted          []string // Resources that were deleted (standard cleanup)
	Purged           []string // Additional resources purged (CNI, orphaned containers, etc.)
}

type PurgeSpaceResult struct {
	Space intmodel.Space

	MetadataDeleted   bool
	CgroupDeleted     bool
	CNINetworkDeleted bool
	PurgeSucceeded    bool
	Force             bool
	Cascade           bool

	Deleted []string // Resources that were deleted (standard cleanup)
	Purged  []string // Additional resources purged (CNI, orphaned containers, etc.)
}

type PurgeStackResult struct {
	Stack   intmodel.Stack
	Deleted []string // Resources that were deleted (standard cleanup)
	Purged  []string // Additional resources purged (CNI, orphaned containers, etc.)
}

type RealmPurgeOutcome struct {
	Name             string
	Namespace        string
	Purged           bool
	NamespaceRemoved bool
	Err              error
}

type RealmSection struct {
	RealmName                          string
	RealmContainerdNamespace           string
	RealmMetadataExistsPre             bool
	RealmMetadataExistsPost            bool
	RealmContainerdNamespaceExistsPre  bool
	RealmContainerdNamespaceExistsPost bool
	RealmContainerdNamespaceCreated    bool
	RealmCreated                       bool
	RealmCgroupExistsPre               bool
	RealmCgroupExistsPost              bool
	RealmCgroupCreated                 bool
}

type ReconcileResult struct {
	CellsScanned int
	CellsUpdated int
	// CellsDeleted counts cells the reconciler removed during the pass
	// because Spec.AutoDelete=true and the root container's task had
	// exited. Tracked separately from CellsUpdated so callers can tell
	// "state flip persisted" apart from "cell is gone".
	CellsDeleted int
	CellsErrored int
	Errors       []string
}

type RefreshResult struct {
	RealmsFound       []string
	SpacesFound       []string
	StacksFound       []string
	CellsFound        []string
	ContainersFound   []string
	RealmsUpdated     []string
	SpacesUpdated     []string
	StacksUpdated     []string
	CellsUpdated      []string
	ContainersUpdated []string
	Errors            []string
}

type ResourceDeleteResult struct {
	Index    int
	Kind     string
	Name     string
	Action   string // "deleted", "not found", "failed"
	Error    error
	Cascaded []string // Child resources deleted (if cascade=true)
	Details  map[string]string
}

type ResourceResult struct {
	Index   int
	Kind    string
	Name    string
	Action  string // "created", "updated", "unchanged", "failed"
	Error   error
	Changes []string
	Details map[string]string
}

type SpaceSection struct {
	SpaceName                 string
	SpaceCNINetworkName       string
	SpaceMetadataExistsPre    bool
	SpaceMetadataExistsPost   bool
	SpaceCNINetworkExistsPre  bool
	SpaceCNINetworkExistsPost bool
	SpaceCNINetworkCreated    bool
	SpaceCreated              bool
	SpaceCgroupExistsPre      bool
	SpaceCgroupExistsPost     bool
	SpaceCgroupCreated        bool
}

type StackSection struct {
	StackName               string
	StackMetadataExistsPre  bool
	StackMetadataExistsPost bool
	StackCreated            bool
	StackCgroupExistsPre    bool
	StackCgroupExistsPost   bool
	StackCgroupCreated      bool
}

type StartCellResult struct {
	Cell    intmodel.Cell
	Started bool
}

type StopCellResult struct {
	Cell    intmodel.Cell
	Stopped bool
}

type UninstallOptions struct {
	// SocketDir is the parent directory of the kukeond unix socket
	// (typically /run/kukeon). Removed recursively when non-empty.
	SocketDir string
	// SystemUser/SystemGroup are the names of the kukeon system user and
	// group to remove. Defaults to "kukeon"/"kukeon" when empty.
	SystemUser  string
	SystemGroup string
	// SkipUserGroup skips userdel/groupdel. Set in tests where touching
	// the host's /etc/passwd is undesirable.
	SkipUserGroup bool
	// UserGroupRemover overrides the default userdel/groupdel routine.
	// Tests inject a stub; production callers leave it nil.
	UserGroupRemover UserGroupRemover
	// KukeondPIDFile points at the kukeond PID file. The daemon-stop step
	// signals the live daemon before any realm purge, so a fight between
	// the in-process PurgeRealm and the running daemon's containerd session
	// can never block the namespace delete with "namespace not empty".
	// Empty disables the daemon-stop step; absent file is a no-op (the
	// partial-uninstall path from #193).
	KukeondPIDFile string
	// DaemonStopper overrides the default PID-file-based stopper. Tests
	// inject a stub; production callers leave it nil.
	DaemonStopper DaemonStopper
	// DaemonStopGracePeriod is the SIGTERM→SIGKILL grace window. Zero uses
	// DefaultDaemonStopGracePeriod (5s).
	DaemonStopGracePeriod time.Duration
	// MountReleaser releases live bind mounts under SocketDir and RunPath
	// before the rmdir step. Production callers leave it nil (defaults to
	// reading /proc/self/mounts + syscall.Unmount); tests inject a stub so
	// they do not have to provision real mounts.
	MountReleaser MountReleaser
	// BuildCacheBaseDir overrides the directory under which `kukebuild`
	// keeps its per-namespace BuildKit state (issue #904). Empty falls
	// back to consts.KukebuildBaseDir; tests pin t.TempDir() so they do
	// not have to write under /var/lib.
	BuildCacheBaseDir string
}

type UninstallReport struct {
	Daemon          DaemonStopReport
	Realms          []RealmPurgeOutcome
	CleanupSkipped  bool
	SocketDir       string
	SocketDirExists bool
	SocketDirRemove bool
	// SocketDirMounts records every kukeon-owned bind mount found under
	// SocketDir at uninstall time and whether it was released. A non-empty
	// list with all entries Released=true is the success path: the rmdir
	// step that follows can now reach an empty directory. Any entry with
	// Err!=nil names a mountpoint the kernel refused to detach — surfacing
	// the busy target so the operator does not have to grep /proc/mounts to
	// find what blocked the teardown (the #434 regression).
	SocketDirMounts []MountReleaseAttempt
	RunPath         string
	RunPathExists   bool
	RunPathRemove   bool
	// RunPathMounts is the RunPath analogue of SocketDirMounts; the run
	// path is checked separately so a busy mount under /opt/kukeon does not
	// mask a busy mount under /run/kukeon (and vice versa).
	RunPathMounts []MountReleaseAttempt
	UserName      string
	UserExisted   bool
	UserRemoved   bool
	GroupName     string
	GroupExisted  bool
	GroupRemoved  bool
	// BuildCaches records the per-namespace BuildKit state directories the
	// uninstall pass reclaimed (issue #904). One entry per realm whose
	// containerd namespace was successfully removed; ordered to match
	// Realms. A realm whose namespace survived contributes no entry —
	// leaving its cache in place is intentional, see BuildCachePurgeOutcome.
	BuildCaches []BuildCachePurgeOutcome
	// BuildCacheBaseDir is the directory the renderer attempted to rmdir
	// after the per-namespace sweep. Empty when no BuildKit cache was
	// touched (no realm purged with NamespaceRemoved=true).
	BuildCacheBaseDir string
	// BuildCacheBaseExisted reports whether BuildCacheBaseDir existed at
	// the start of the rmdir step (after the per-namespace sweep). Lets the
	// renderer distinguish "absent" from "kept".
	BuildCacheBaseExisted bool
	// BuildCacheBaseRemoved reports whether BuildCacheBaseDir was rmdir'd.
	// Only true when the base directory was empty after the per-namespace
	// sweep — a scoped uninstall (`--server-configuration` narrowing the
	// realm set) leaves cousin-instance caches untouched and the base dir
	// stays. Plain `os.Remove`, not `RemoveAll`: stomping on another
	// instance's cache would be a regression of the scoping invariant.
	BuildCacheBaseRemoved bool
}

type UserGroupRemovalReport struct {
	UserExisted  bool
	UserRemoved  bool
	GroupExisted bool
	GroupRemoved bool
}

type UserGroupRemover func(ctx context.Context, user, group string) (UserGroupRemovalReport, error)