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 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
}

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)
	CreateContainer(container intmodel.Container) (CreateContainerResult, 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)
	DeleteContainer(container intmodel.Container) (DeleteContainerResult, 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)
	StartContainer(container intmodel.Container) (StartContainerResult, error)
	StopCell(cell intmodel.Cell) (StopCellResult, error)
	StopContainer(container intmodel.Container) (StopContainerResult, error)
	KillCell(cell intmodel.Cell) (KillCellResult, error)
	KillContainer(container intmodel.Container) (KillContainerResult, 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)
	PurgeContainer(container intmodel.Container) (PurgeContainerResult, 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 CreateContainerResult struct {
	Container intmodel.Container

	CellMetadataExistsPre  bool
	CellMetadataExistsPost bool
	ContainerExistsPre     bool
	ContainerExistsPost    bool
	ContainerCreated       bool
	Started                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 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 DeleteCellResult struct {
	Cell              intmodel.Cell
	ContainersDeleted bool
	CgroupDeleted     bool
	MetadataDeleted   bool
}

type DeleteContainerResult struct {
	Container          intmodel.Container
	CellMetadataExists bool
	ContainerExists    bool
	Deleted            []string // Resources that were deleted (container, task)
}

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 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 GetCellResult struct {
	Cell                intmodel.Cell
	MetadataExists      bool
	CgroupExists        bool
	RootContainerExists 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 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 KillContainerResult struct {
	Container intmodel.Container
	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
}

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 PurgeContainerResult struct {
	Container          intmodel.Container
	CellMetadataExists bool
	ContainerExists    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 StartContainerResult struct {
	Container intmodel.Container
	Started   bool
}

type StopCellResult struct {
	Cell    intmodel.Cell
	Stopped bool
}

type StopContainerResult struct {
	Container intmodel.Container
	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
}

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
}

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

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