modelhub

type Cell struct {
	Metadata CellMetadata
	Spec     CellSpec
	Status   CellStatus
}

type CellBindingRef struct {
	Name  string
	Realm string
	Space string
	Stack string
}

type CellBlueprint struct {
	Metadata CellBlueprintMetadata
	Document []byte
}

type CellBlueprintMetadata struct {
	Name  string
	Realm string
	Space string
	Stack string
	// Labels lifts the blueprint document's metadata.labels onto the carrier
	// so daemon-side code can filter (`kukeon.io/team=<team>` for
	// per-team prune apply, #1027) without re-parsing the Document on every
	// access. ListBlueprints populates it; WriteBlueprint preserves it via
	// the Document round-trip — the labels travel inside the canonical
	// serialized doc, the carrier just lifts a typed view.
	Labels map[string]string
}

type CellConfig struct {
	Metadata CellConfigMetadata
	Document []byte
}

type CellConfigMetadata struct {
	Name  string
	Realm string
	Space string
	Stack string
	// Labels lifts the config document's metadata.labels onto the carrier
	// so daemon-side code can filter (`kukeon.io/team=<team>` for per-team
	// prune apply, #1027) without re-parsing the Document on every access.
	// ListConfigs populates it; WriteConfig preserves it via the Document
	// round-trip — the labels travel inside the canonical serialized doc,
	// the carrier just lifts a typed view.
	Labels map[string]string
}

type CellMetadata struct {
	Name   string
	Labels map[string]string
	// Annotations mirror v1beta1.CellMetadata.Annotations: non-identifying
	// metadata that round-trips through cell metadata but that no reconcile or
	// selector path keys off, and that DiffCell does not compare. Carries a
	// clone's `kukeon.io/source-cell` provenance annotation (#1073).
	Annotations map[string]string
	// Generation is a monotonic counter bumped by a writer on each
	// spec-changing update. Defaults to zero; phase 3 wires the writers to
	// populate it. See ObservedGeneration on the status.
	Generation int64
}

type CellNetworkStatus struct {
	BridgeName string
}

type CellProvenance struct {
	BindingKind  string
	BindingRef   CellBindingRef
	Params       map[string]string
	EnvOverrides []string
}

type CellSpec struct {
	ID              string
	RealmName       string
	SpaceName       string
	StackName       string
	RootContainerID string
	Tty             *CellTty
	Containers      []ContainerSpec
	// AutoDelete mirrors v1beta1.CellSpec.AutoDelete. See that type for
	// semantics; the field is round-tripped through cell metadata so the
	// daemon can re-derive the auto-delete intent after a restart.
	AutoDelete bool
	// NestedCgroupRuntime mirrors v1beta1.CellSpec.NestedCgroupRuntime. See
	// that type for semantics; the field is round-tripped through cell
	// metadata so the daemon can re-toggle the full subtree controller set
	// on the ensure-pass after a restart.
	NestedCgroupRuntime bool
	// RuntimeEnv mirrors v1beta1.CellSpec.RuntimeEnv. The wire side carries
	// `kuke run --env KEY=VALUE` from the CLI; the daemon merges these
	// entries into the attachable container's OCI process env at create /
	// start time. NOT persisted (v1beta1 has yaml:"-") — the runtime cell
	// metadata.yaml never carries it, so the disk-read paths
	// (validateAndGetCell, runner.GetCell) return cells with an empty
	// RuntimeEnv. Callers that drive a fresh start/recreate from a CLI
	// request preserve the field by copying cell.Spec.RuntimeEnv from the
	// inbound RPC cell onto the disk-read cell before the OCI build. See
	// runner.startCellLocked and Exec.createCellInternal. Issue #834.
	RuntimeEnv []string
	// Provenance mirrors v1beta1.CellSpec.Provenance: the persisted record of
	// the binding (Config or Blueprint) and the scalar params / env overrides
	// this cell was materialized from. Unlike RuntimeEnv it round-trips
	// through cell metadata so the reconciler can re-resolve the binding after
	// a restart. Nil for hand-built cells. DiffCell ignores it (lineage data,
	// not a runtime spec field). Issue #1021.
	Provenance *CellProvenance
	// IgnoreDiskPressure mirrors v1beta1.CellSpec.IgnoreDiskPressure. The wire
	// side carries `kuke create cell`/`kuke run --ignore-disk-pressure` from
	// the CLI; the runner's CreateCell guard reads it to bypass the data-volume
	// disk-pressure block. NOT persisted (v1beta1 has yaml:"-") — the override
	// is per-invocation, so the disk-read paths return cells with it false.
	// Issue #1035.
	IgnoreDiskPressure bool
}

type CellState int

type CellStatus struct {
	State      CellState
	CgroupPath string
	// SubtreeControllers records the cgroup-v2 controllers actually
	// delegated on this cell's own cgroup.subtree_control after the
	// effective filter against the host root's cgroup.controllers
	// (issue #328). For NestedCgroupRuntime cells this carries the full
	// host-available set; for ordinary cells it carries the kukeon
	// resource subset (cgroupcheck.CellResourceControllers).
	SubtreeControllers []string
	Network            CellNetworkStatus
	Containers         []ContainerStatus
	// ReadyObserved is a one-way latch set the first time the cell has
	// been observed Ready by ReconcileCell — either via the freshly
	// derived state or via a persisted Ready state from a prior
	// observation (or a synchronous Start that wrote Ready before the
	// reconciler got there). The latch gates Spec.AutoDelete cleanup so
	// a cell that has never been Ready (e.g. mid-creation, between
	// cgroup setup and root-container registration, where
	// GetContainerState reports Stopped for a not-yet-existing
	// container) cannot be reaped by the reconciler.
	ReadyObserved bool
	// Lifecycle and runtime-health fields (issue #166). See
	// RealmStatus for the per-field contract.
	CreatedAt   time.Time
	UpdatedAt   time.Time
	ReadyAt     time.Time
	Reason      string
	Message     string
	CgroupReady bool
	// ObservedGeneration is the Metadata.Generation the reconciler last
	// acted on. Defaults to zero; phase 3 wires the reconciler to compare
	// it against Generation to skip stale work.
	ObservedGeneration int64
	// OutOfSync is true when the daemon's reconciler detects that this
	// cell's live spec has diverged from what its lineage Config would
	// materialize (issue #820, foundation phase of #819's umbrella). Only
	// set on cells carrying the kukeon.io/config lineage label; cells
	// without that label leave it false. OutOfSyncReason carries a short
	// human-readable summary when true. OutOfSyncError carries a distinct
	// failure surface when the reconciler could not compute divergence at
	// all (referenced Blueprint missing, materialization error) — when
	// non-empty, OutOfSync stays false because divergence is undecidable.
	OutOfSync       bool
	OutOfSyncReason string
	OutOfSyncError  string
}

type CellTty struct {
	Default string
}

type Container struct {
	Metadata ContainerMetadata
	Spec     ContainerSpec
	Status   ContainerStatus
}

type ContainerCapabilities struct {
	Drop []string
	Add  []string
}

type ContainerGit struct {
	Author         *GitIdentity
	Committer      *GitIdentity
	SigningKey     string
	Sign           []string
	AllowedSigners string
}

type ContainerMetadata struct {
	Name   string
	Labels map[string]string
}

type ContainerRepo struct {
	Name     string
	Target   string
	Branch   string
	Ref      string
	URL      string
	Required bool
}

type ContainerResources struct {
	MemoryLimitBytes *int64
	CPUShares        *int64
	PidsLimit        *int64
}

type ContainerSecret struct {
	Name      string
	FromFile  string
	FromEnv   string
	SecretRef *ContainerSecretRef
	MountPath string
}

type ContainerSecretRef struct {
	Name  string
	Realm string
	Space string
	Stack string
	Cell  string
}

type ContainerSpec struct {
	ID              string
	ContainerdID    string
	RealmName       string
	SpaceName       string
	StackName       string
	CellName        string
	Root            bool
	Image           string
	Command         string
	Args            []string
	WorkingDir      string
	Env             []string
	Ports           []string
	Volumes         []VolumeMount
	Networks        []string
	NetworksAliases []string
	Privileged      bool
	HostNetwork     bool
	HostPID         bool
	HostCgroup      bool
	// NestedCgroupRuntime mirrors the parent cell's
	// CellSpec.NestedCgroupRuntime opt-in (issue #314). When true and
	// !HostCgroup, BuildContainerSpec/BuildRootContainerSpec append a
	// cgroup2 mount at /sys/fs/cgroup so an inner runtime (dockerd,
	// podman, an inner containerd) can read the controller set that
	// the controller delegated host-side via
	// EnableCellAllSubtreeControllers (#318). Propagated by the runner
	// from cell.Spec.NestedCgroupRuntime at every BuildContainerSpec
	// call site; not part of the persisted container document.
	NestedCgroupRuntime    bool
	User                   string
	ReadOnlyRootFilesystem bool
	Capabilities           *ContainerCapabilities
	SecurityOpts           []string
	// Devices mirrors the v1beta1 ContainerSpec.Devices payload — individual
	// host device nodes granted to the container (least-privilege alternative
	// to Privileged). Each entry is a host device path (short form, e.g.
	// "/dev/kvm") replicated at the same in-container path with "rwm" access.
	// BuildContainerSpec emits a Linux.Devices entry + Linux.Resources.Devices
	// allow rule per entry, stat'd from the host node at create time. Issue
	// #1252.
	Devices   []string
	Tmpfs     []ContainerTmpfsMount
	Resources *ContainerResources
	Secrets   []ContainerSecret
	// Repos mirrors the v1beta1 ContainerSpec.Repos payload — git
	// repositories kuketty clones/fetches in its pre-Serve step. See the
	// v1beta1 type for field semantics. Issue #617.
	Repos []ContainerRepo
	// Git mirrors the v1beta1 ContainerSpec.Git payload — declarative git
	// identity/signing sugar that BuildContainerSpec / BuildRootContainerSpec
	// expand into the GIT_AUTHOR_* / GIT_COMMITTER_* / GIT_CONFIG_* env block.
	// See the v1beta1 type for field semantics. Issue #618.
	Git           *ContainerGit
	CNIConfigPath string
	// RestartPolicy is the user-authored restart policy applied to the
	// container when its task exits. See the RestartPolicy* constants
	// below for the canonical values; the runner's wind-down/auto-delete
	// gate (refresh.go:restartPolicyPermitsCellReap) is the only consumer
	// today. Empty/unset is treated as RestartPolicyAlways for
	// back-compat — the pre-#1003 wind-down behavior, where every
	// non-root container exit can trigger a cell-level wind-down.
	RestartPolicy string
	Attachable    bool
	Tty           *ContainerTty
	// CellCgroupPath is the absolute cgroup path of the parent cell (mirrors
	// Cell.Status.CgroupPath). When set, BuildContainerSpec emits an OCI
	// Linux.CgroupsPath rooted at <CellCgroupPath>/<containerd-id> so the
	// container task lands inside the cell's cgroup subtree instead of
	// containerd's runc-shim default placement. Populated by the runner at
	// container-create time; not part of the persisted cell document.
	CellCgroupPath string
	// EtcHostsPath is the host-side path of a kukeond-rendered /etc/hosts file
	// to bind-mount at /etc/hosts inside the container. Empty disables the
	// bind-mount, leaving the image's /etc/hosts in place. Mirrors Docker's
	// per-container hosts pattern; the source file lives under the cell's
	// metadata directory so cell teardown cleans it up. Populated by the
	// runner at container-create time; not part of the persisted document.
	EtcHostsPath string
	// EtcHostnamePath is the host-side path of a kukeond-rendered /etc/hostname
	// file (cell name) to bind-mount at /etc/hostname inside the container.
	// Empty disables the bind-mount. Same lifecycle and storage location as
	// EtcHostsPath; not part of the persisted document.
	EtcHostnamePath string
}

type ContainerState int

type ContainerStatus struct {
	Name string // Container name/ID
	ID   string // Container ID (same as Name)
	// CreatedAt is the wall-clock time of the first time the controller
	// observed this container in cell.Spec.Containers. Stamped on the
	// first populateCellContainerStatuses pass and preserved across
	// reconciliations. Sources the AGE column on `kuke get container`.
	CreatedAt    time.Time
	State        ContainerState
	RestartCount int
	RestartTime  time.Time
	StartTime    time.Time
	FinishTime   time.Time
	ExitCode     int
	ExitSignal   string
	// Repos reports the per-repo outcome of kuketty's pre-Serve clone/fetch
	// step. Mirrors the v1beta1 ContainerStatus.Repos payload. Issue #617.
	Repos []RepoStatus
	// Stages reports the per-stage outcome of kuketty's pre-Serve execution of
	// the container's runOn: create stages. Mirrors the v1beta1
	// ContainerStatus.Stages payload; schema only this phase, populated in
	// phase B (#689). Issue #635.
	Stages []StageStatus
}

type ContainerTmpfsMount struct {
	Path      string
	SizeBytes int64
	Options   []string
}

type ContainerTty struct {
	Prompt   string
	OnInit   []TtyStage
	LogFile  string
	LogLevel string
}

type EgressAllowRule struct {
	Host  string
	CIDR  string
	Ports []int
}

type EgressDefault string

type EgressPolicy struct {
	Default EgressDefault
	Allow   []EgressAllowRule
}

type GitIdentity struct {
	Name  string
	Email string
}

type Realm struct {
	Metadata RealmMetadata
	Spec     RealmSpec
	Status   RealmStatus
}

type RealmMetadata struct {
	Name   string
	Labels map[string]string
	// Generation is a monotonic counter bumped by a writer on each
	// spec-changing update. Defaults to zero; phase 3 (issue #596 follow-up)
	// wires the writers to populate it. See ObservedGeneration on the status.
	Generation int64
}

type RealmSpec struct {
	Namespace           string
	RegistryCredentials []RegistryCredentials
}

type RealmState int

type RealmStatus struct {
	State      RealmState
	CgroupPath string
	// SubtreeControllers records the cgroup-v2 controllers actually
	// delegated on this realm's own cgroup.subtree_control after the
	// effective filter against the host root's cgroup.controllers (issue
	// #328, surfacing the result of the helper landed by issue #327).
	SubtreeControllers []string
	// CreatedAt is the wall-clock time of the first persist. Stamped
	// only when zero so the value never moves once set (issue #166).
	CreatedAt time.Time
	// UpdatedAt is the wall-clock time of the most recent persist.
	UpdatedAt time.Time
	// ReadyAt is the wall-clock time of the first State==Ready persist.
	// Set-once: never overwritten by subsequent Ready transitions.
	ReadyAt time.Time
	// Reason is a short reason code summarizing why State is in its
	// current value. Empty when no reason has been recorded.
	Reason string
	// Message is the human-readable detail backing Reason.
	Message string
	// CgroupReady reports whether CgroupPath was observed to exist on
	// the host filesystem as of the last status write.
	CgroupReady bool
	// ContainerdNamespaceReady reports whether the realm's containerd
	// namespace was observed to exist as of the last status write.
	ContainerdNamespaceReady bool
	// ObservedGeneration is the Metadata.Generation the reconciler last
	// acted on. Defaults to zero; phase 3 wires the reconciler to compare
	// it against Generation to skip stale work.
	ObservedGeneration int64
}

type RegistryCredentials struct {
	// Username is the registry username.
	Username string
	// Password is the registry password or token.
	Password string
	// ServerAddress is the registry server address (e.g., "docker.io", "registry.example.com").
	// If empty, credentials apply to the registry extracted from the image reference.
	ServerAddress string
}

type RepoStatus struct {
	Name   string
	Target string
	State  string
	Commit string
	Error  string
}

type Secret struct {
	Metadata SecretMetadata
	Spec     SecretSpec
}

type SecretMetadata struct {
	Name  string
	Realm string
	Space string
	Stack string
	Cell  string
}

type SecretSpec struct {
	Data string
}

type Space struct {
	Metadata SpaceMetadata
	Spec     SpaceSpec
	Status   SpaceStatus
}

type SpaceContainerDefaults struct {
	User                   string
	ReadOnlyRootFilesystem *bool
	Capabilities           *ContainerCapabilities
	SecurityOpts           []string
	Tmpfs                  []ContainerTmpfsMount
	Resources              *ContainerResources
}

type SpaceDefaults struct {
	Container *SpaceContainerDefaults
}

type SpaceMetadata struct {
	Name   string
	Labels map[string]string
	// Generation is a monotonic counter bumped by a writer on each
	// spec-changing update. Defaults to zero; phase 3 wires the writers to
	// populate it. See ObservedGeneration on the status.
	Generation int64
}

type SpaceNetwork struct {
	Egress *EgressPolicy
}

type SpaceSpec struct {
	RealmName     string
	CNIConfigPath string
	Network       *SpaceNetwork
	Defaults      *SpaceDefaults
}

type SpaceState int

type SpaceStatus struct {
	State      SpaceState
	CgroupPath string
	// SubtreeControllers records the cgroup-v2 controllers actually
	// delegated on this space's own cgroup.subtree_control after the
	// effective filter against the host root's cgroup.controllers (issue
	// #328).
	SubtreeControllers []string
	// Lifecycle and runtime-health fields (issue #166). See
	// RealmStatus for the per-field contract.
	CreatedAt   time.Time
	UpdatedAt   time.Time
	ReadyAt     time.Time
	Reason      string
	Message     string
	CgroupReady bool
	// ObservedGeneration is the Metadata.Generation the reconciler last
	// acted on. Defaults to zero; phase 3 wires the reconciler to compare
	// it against Generation to skip stale work.
	ObservedGeneration int64
}

type Stack struct {
	Metadata StackMetadata
	Spec     StackSpec
	Status   StackStatus
}

type StackMetadata struct {
	Name   string
	Labels map[string]string
	// Generation is a monotonic counter bumped by a writer on each
	// spec-changing update. Defaults to zero; phase 3 wires the writers to
	// populate it. See ObservedGeneration on the status.
	Generation int64
}

type StackSpec struct {
	ID        string
	RealmName string
	SpaceName string
}

type StackState int

type StackStatus struct {
	State      StackState
	CgroupPath string
	// SubtreeControllers records the cgroup-v2 controllers actually
	// delegated on this stack's own cgroup.subtree_control after the
	// effective filter against the host root's cgroup.controllers (issue
	// #328).
	SubtreeControllers []string
	// Lifecycle and runtime-health fields (issue #166). See
	// RealmStatus for the per-field contract.
	CreatedAt   time.Time
	UpdatedAt   time.Time
	ReadyAt     time.Time
	Reason      string
	Message     string
	CgroupReady bool
	// ObservedGeneration is the Metadata.Generation the reconciler last
	// acted on. Defaults to zero; phase 3 wires the reconciler to compare
	// it against Generation to skip stale work.
	ObservedGeneration int64
}

type StageStatus struct {
	Index int
	State string
	Error string
	// Hash is the content hash of the stage at record time — the run-once
	// "done" key. See the v1beta1 type for the merge contract.
	Hash string
}

type TtyStage struct {
	Script string
	RunOn  string
}

type VolumeKind string

type VolumeMount struct {
	Kind     VolumeKind
	Source   string
	Target   string
	ReadOnly bool
	// SizeBytes is the tmpfs size= option in bytes. Only honored when
	// Kind == VolumeKindTmpfs; zero leaves the kernel default.
	SizeBytes int64
	// Mode is the tmpfs mode= option as a 4-digit octal value (e.g. 0755).
	// Only honored when Kind == VolumeKindTmpfs; zero leaves the kernel
	// default (01777).
	Mode uint32
}