spec

type AUR struct {
	Package []PackageItem `yaml:"package,omitempty" json:"package,omitempty"`

	Options []string `yaml:"option,omitempty" json:"option,omitempty"`

	Replaces []string `yaml:"replace,omitempty" json:"replace,omitempty"`
}

type AdbEndpoint struct {
	Host string `yaml:"host,omitempty" json:"host"`
}

type Agent struct {
	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	Command []string `yaml:"command,omitempty" json:"command"`

	PromptVia string `yaml:"prompt_via,omitempty" json:"prompt_via"`

	VersionCommand []string `yaml:"version_command,omitempty" json:"version_command,omitempty"`

	Timeout Duration `yaml:"timeout,omitempty" json:"timeout,omitempty"`

	Env StrMap `yaml:"env,omitempty" json:"env,omitempty"`

	WorkingDir string `yaml:"working_dir,omitempty" json:"working_dir,omitempty"`

	Credential []CredentialMount `yaml:"credential,omitempty" json:"credential,omitempty"`

	ProgressCheckInterval Duration `yaml:"progress_check_interval,omitempty" json:"progress_check_interval,omitempty"`

	ProgressNoImprovementTimeout Duration `yaml:"progress_no_improvement_timeout,omitempty" json:"progress_no_improvement_timeout,omitempty"`

	OutputFormat string `yaml:"output_format,omitempty" json:"output_format"`
}

type AgentAbortControl struct {
	RunID UUIDv7 `yaml:"run_id,omitempty" json:"run_id"`

	RequestID UUIDv7 `yaml:"request_id,omitempty" json:"request_id"`

	RequestedAt string `yaml:"requested_at,omitempty" json:"requested_at"`
}

type AgentDelegationEdge struct {
	From string `yaml:"from,omitempty" json:"from"`

	To string `yaml:"to,omitempty" json:"to"`

	Allow []string `yaml:"allow,omitempty" json:"allow,omitempty"`
}

type AgentEvent struct {
	RunID UUIDv7 `yaml:"run_id,omitempty" json:"run_id"`

	Sequence int64 `yaml:"sequence,omitempty" json:"sequence"`

	Type string `yaml:"type,omitempty" json:"type"`

	Time string `yaml:"time,omitempty" json:"time"`

	Payload map[string]any `yaml:"payload,omitempty" json:"payload,omitempty"`
}

type AgentExecSpec struct {
	Command []string `yaml:"command,omitempty" json:"command,omitempty"`

	PromptVia string `yaml:"prompt_via,omitempty" json:"prompt_via,omitempty"`

	VersionCommand []string `yaml:"version_command,omitempty" json:"version_command,omitempty"`

	Timeout Duration `yaml:"timeout,omitempty" json:"timeout,omitempty"`

	Env StrMap `yaml:"env,omitempty" json:"env,omitempty"`

	WorkingDir string `yaml:"working_dir,omitempty" json:"working_dir,omitempty"`

	Credential []CredentialMount `yaml:"credential,omitempty" json:"credential,omitempty"`

	ProgressCheckInterval Duration `yaml:"progress_check_interval,omitempty" json:"progress_check_interval,omitempty"`

	ProgressNoImprovementTimeout Duration `yaml:"progress_no_improvement_timeout,omitempty" json:"progress_no_improvement_timeout,omitempty"`

	OutputFormat string `yaml:"output_format,omitempty" json:"output_format,omitempty"`
}

type AgentFederationRecord struct {
	ID UUIDv7 `yaml:"id,omitempty" json:"id"`

	Node string `yaml:"node,omitempty" json:"node"`

	Owner string `yaml:"owner,omitempty" json:"owner"`

	SessionID UUIDv7 `yaml:"session_id,omitempty" json:"session_id,omitempty"`

	RunID UUIDv7 `yaml:"run_id,omitempty" json:"run_id,omitempty"`

	State string `yaml:"state,omitempty" json:"state"`

	UpdatedAt string `yaml:"updated_at,omitempty" json:"updated_at"`

	Metadata StrMap `yaml:"metadata,omitempty" json:"metadata,omitempty"`
}

type AgentResolveInput struct {
	Agents map[string]RawBody `yaml:"agents,omitempty" json:"agents,omitempty"`

	Name string `yaml:"name,omitempty" json:"name,omitempty"`
}

type AgentResolveReply struct {
	Spec *AgentExecSpec `yaml:"spec,omitempty" json:"spec,omitempty"`

	Name string `yaml:"name,omitempty" json:"name,omitempty"`
}

type AgentRunRequest struct {
	ID UUIDv7 `yaml:"id,omitempty" json:"id"`

	SessionID UUIDv7 `yaml:"session_id,omitempty" json:"session_id"`

	RequestID UUIDv7 `yaml:"request_id,omitempty" json:"request_id"`

	IdempotencyKey string `yaml:"idempotency_key,omitempty" json:"idempotency_key"`

	Prompt string `yaml:"prompt,omitempty" json:"prompt,omitempty"`

	Params map[string]any `yaml:"params,omitempty" json:"params,omitempty"`

	Resume bool `yaml:"resume,omitempty" json:"resume,omitempty"`
}

type AgentRuntimeCapability struct {
	Provider string `yaml:"provider,omitempty" json:"provider"`

	ProtocolVersion int `yaml:"protocol_version,omitempty" json:"protocol_version"`

	Entrypoint []string `yaml:"entrypoint,omitempty" json:"entrypoint,omitempty"`

	Profiles []string `yaml:"profiles,omitempty" json:"profiles,omitempty"`

	InteractionModes []string `yaml:"interaction_modes,omitempty" json:"interaction_modes,omitempty"`

	Persistence string `yaml:"persistence,omitempty" json:"persistence,omitempty"`

	SemanticCompletion bool `yaml:"semantic_completion,omitempty" json:"semantic_completion,omitempty"`
}

type AgentSession struct {
	ID UUIDv7 `yaml:"id,omitempty" json:"id"`

	Runtime string `yaml:"runtime,omitempty" json:"runtime"`

	Target TargetSpec `yaml:"target,omitempty" json:"target"`

	State string `yaml:"state,omitempty" json:"state"`

	CreatedAt string `yaml:"created_at,omitempty" json:"created_at"`

	UpdatedAt string `yaml:"updated_at,omitempty" json:"updated_at"`

	StorageRef string `yaml:"storage_ref,omitempty" json:"storage_ref,omitempty"`

	Metadata StrMap `yaml:"metadata,omitempty" json:"metadata,omitempty"`

	TerminalProfile *TerminalProfile `yaml:"terminal_profile,omitempty" json:"terminal_profile,omitempty"`
}

type AgentSessionBinding struct {
	StorageRef string `yaml:"storage_ref,omitempty" json:"storage_ref"`
}

type AgentTeam struct {
	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	Agents []AgentTeamMember `yaml:"agents,omitempty" json:"agents"`

	Edges []AgentDelegationEdge `yaml:"edges,omitempty" json:"edges,omitempty"`

	Coordinator string `yaml:"coordinator,omitempty" json:"coordinator,omitempty"`

	Concurrency int64 `yaml:"concurrency,omitempty" json:"concurrency,omitempty"`

	EvidencePolicy string `yaml:"evidence_policy,omitempty" json:"evidence_policy,omitempty"`
}

type AgentTeamMember struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Runtime string `yaml:"runtime,omitempty" json:"runtime"`

	Role string `yaml:"role,omitempty" json:"role,omitempty"`

	Target TargetSpec `yaml:"target,omitempty" json:"target,omitempty"`

	TerminalProfile *TerminalProfile `yaml:"terminal_profile,omitempty" json:"terminal_profile,omitempty"`
}

type AgentTeamRecord struct {
	ID UUIDv7 `yaml:"id,omitempty" json:"id"`

	Team AgentTeam `yaml:"team,omitempty" json:"team"`

	Sessions map[string]UUIDv7 `yaml:"sessions,omitempty" json:"sessions"`

	CreatedAt string `yaml:"created_at,omitempty" json:"created_at"`
}

type AggregatedCandyCaps struct {
	PreserveUser bool `yaml:"preserve_user,omitempty" json:"preserve_user,omitempty"`

	NeedsRootAfterInit bool `yaml:"needs_root_after_init,omitempty" json:"needs_root_after_init,omitempty"`

	InitSystemHint string `yaml:"init_system_hint,omitempty" json:"init_system_hint,omitempty"`

	DataOnly bool `yaml:"data_only,omitempty" json:"data_only,omitempty"`

	OCILabels map[string]string `yaml:"oci_labels,omitempty" json:"oci_labels,omitempty"`

	// provided is the set of capability names declared by some candy in the composition.
	// Used by CheckRequiredCapabilities to validate `requires_capabilities:` cross-candy
	// requirements.
	Provided map[string]bool `yaml:"provided,omitempty" json:"provided,omitempty"`
}

type AggregatedCandyCapsView struct {
	PreserveUser bool `yaml:"preserve_user,omitempty" json:"preserve_user,omitempty"`

	NeedsRootAfterInit bool `yaml:"needs_root_after_init,omitempty" json:"needs_root_after_init,omitempty"`

	OCILabels map[string]string `yaml:"oci_labels,omitempty" json:"oci_labels,omitempty"`
}

type AliasConfig = BoxAlias

type AliasYAML = CandyAlias

type AlpineBootstrap struct {
	MirrorURL string `yaml:"mirror_url,omitempty" json:"mirror_url,omitempty"`
}

type Android struct {
	Serial string `yaml:"serial,omitempty" json:"serial,omitempty"`

	Device string `yaml:"device,omitempty" json:"device,omitempty"`

	ApiLevel int `yaml:"api_level,omitempty" json:"api_level,omitempty"`

	GoogleAccount *GoogleAccount `yaml:"google_account,omitempty" json:"google_account,omitempty"`

	Plan []Step `yaml:"plan,omitempty" json:"plan,omitempty"`

	// Device source — exactly one of box/adb (enforced in Go, see header).
	Box string `yaml:"box,omitempty" json:"box,omitempty"`

	Adb *AdbEndpoint `yaml:"adb,omitempty" json:"adb,omitempty"`
}

type AndroidDeployVenue struct {
	AdbAddr string `yaml:"adb_addr,omitempty" json:"adb_addr"`

	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`

	Container string `yaml:"container,omitempty" json:"container,omitempty"`

	Serial string `yaml:"serial,omitempty" json:"serial,omitempty"`

	GoogleEmail string `yaml:"google_email,omitempty" json:"google_email,omitempty"`

	GoogleToken string `yaml:"google_token,omitempty" json:"google_token,omitempty"`

	Installs []ApkPackageSpec `yaml:"installs,omitempty" json:"installs,omitempty"`

	// boot_timeout / install_deadline / install_interval are the readiness +
	// install-retry windows the host ships (no magic numbers in the plugin).
	BootTimeout string `yaml:"boot_timeout,omitempty" json:"boot_timeout,omitempty"`

	InstallDeadline string `yaml:"install_deadline,omitempty" json:"install_deadline,omitempty"`

	InstallInterval string `yaml:"install_interval,omitempty" json:"install_interval,omitempty"`
}

type AndroidEntityResolution struct {
	SpecJSON RawBody `yaml:"spec,omitempty" json:"spec,omitempty"`
}

type AndroidResolveInput struct {
	Android RawBody `yaml:"android,omitempty" json:"android"`
}

type AndroidResolveReply struct {
	Resolved *ResolvedAndroid `yaml:"resolved,omitempty" json:"resolved,omitempty"`
}

type AndroidSpec = Android

type ApkPackageSpec struct {
	Package    string `yaml:"package,omitempty" json:"package,omitempty"`
	Apk        string `yaml:"apk,omitempty" json:"apk,omitempty"`
	Source     string `yaml:"source,omitempty" json:"source,omitempty"`
	Arch       string `yaml:"arch,omitempty" json:"arch,omitempty"`
	AppVersion string `yaml:"app_version,omitempty" json:"app_version,omitempty"`
}

type ArbiterBracketAcquireReply struct {
}

type ArbiterBracketAcquireRequest struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Node Deploy `yaml:"node,omitempty" json:"node"`
}

type ArbiterBracketReleaseReply struct {
}

type ArbiterBracketReleaseRequest struct {
	Name string `yaml:"name,omitempty" json:"name"`
}

type ArbiterInvokeInput struct {
	Action string `yaml:"action,omitempty" json:"action"`

	Claimant string `yaml:"claimant,omitempty" json:"claimant,omitempty"`

	Tokens []string `yaml:"tokens,omitempty" json:"tokens,omitempty"`

	ClaimAddr HolderAddr `yaml:"claim_addr,omitempty" json:"claim_addr"`

	Transient bool `yaml:"transient,omitempty" json:"transient,omitempty"`

	Success bool `yaml:"success,omitempty" json:"success,omitempty"`

	Token string `yaml:"token,omitempty" json:"token,omitempty"`
}

type ArbiterInvokeReply struct {
	Active bool `yaml:"active,omitempty" json:"active,omitempty"`

	Bool bool `yaml:"bool,omitempty" json:"bool,omitempty"`

	Ledger *PreemptLedger `yaml:"ledger,omitempty" json:"ledger,omitempty"`

	Stranded []string `yaml:"stranded,omitempty" json:"stranded,omitempty"`

	Error string `yaml:"error,omitempty" json:"error,omitempty"`
}

type ArtifactView struct {
	ContainerPath string `yaml:"container_path,omitempty" json:"container_path,omitempty"`

	HostPath string `yaml:"host_path,omitempty" json:"host_path,omitempty"`

	Chown bool `yaml:"chown,omitempty" json:"chown,omitempty"`
}

type BakePluginsReply struct {
	Fragment string `yaml:"fragment,omitempty" json:"fragment,omitempty"`

	Error string `yaml:"error,omitempty" json:"error,omitempty"`
}

type BakePluginsRequest struct {
	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`

	BoxName string `yaml:"box_name,omitempty" json:"box_name"`

	CandyOrder []string `yaml:"candy_order,omitempty" json:"candy_order,omitempty"`
}

type BakedLabelSet struct {
	// always-present scalars (the formatter emits these unconditionally as LABEL %q).
	Version string `yaml:"version,omitempty" json:"version"`

	Box string `yaml:"box,omitempty" json:"box"`

	UID int `yaml:"uid,omitempty" json:"uid"`

	GID int `yaml:"gid,omitempty" json:"gid"`

	User string `yaml:"user,omitempty" json:"user"`

	Home string `yaml:"home,omitempty" json:"home"`

	// conditional scalars (the formatter omits these when empty).
	Registry string `yaml:"registry,omitempty" json:"registry,omitempty"`

	Bootc bool `yaml:"bootc,omitempty" json:"bootc,omitempty"`

	OCILabels map[string]string `yaml:"oci_labels,omitempty" json:"oci_labels,omitempty"`

	Network string `yaml:"network,omitempty" json:"network,omitempty"`

	// platform identity + builder-pool coordination (writeJSONLabel).
	Distro []string `yaml:"distro,omitempty" json:"distro,omitempty"`

	BuildFormat []string `yaml:"build_format,omitempty" json:"build_format,omitempty"`

	Builder map[string]string `yaml:"builder,omitempty" json:"builder,omitempty"`

	Build []string `yaml:"build,omitempty" json:"build,omitempty"`

	// JSON labels (omitted when empty). env is the image-level env MAP (the label wire form).
	Port []string `yaml:"port,omitempty" json:"port,omitempty"`

	PortProto map[string]string `yaml:"port_proto,omitempty" json:"port_proto,omitempty"`

	Volume []LabelVolumeEntry `yaml:"volume,omitempty" json:"volume,omitempty"`

	Alias []CollectedAlias `yaml:"alias,omitempty" json:"alias,omitempty"`

	Security Security `yaml:"security,omitempty" json:"security,omitempty"`

	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`

	Hook *CandyHook `yaml:"hook,omitempty" json:"hook,omitempty"`

	Description *LabelDescriptionSet `yaml:"description,omitempty" json:"description,omitempty"`

	Shell *LabelShellSet `yaml:"shell,omitempty" json:"shell,omitempty"`

	// init system: active name + the deploy-relevant init def + the DYNAMIC label key the
	// per-init service-name list emits under (writeJSONLabel(b, labelInitDef.LabelKey, names)).
	Init string `yaml:"init,omitempty" json:"init,omitempty"`

	InitDef *CapabilityInitDef `yaml:"init_def,omitempty" json:"init_def,omitempty"`

	InitLabelKey string `yaml:"init_label_key,omitempty" json:"init_label_key,omitempty"`

	ServiceNames []string `yaml:"service_names,omitempty" json:"service_names,omitempty"`

	Service []CapabilityService `yaml:"service,omitempty" json:"service,omitempty"`

	PortRelay []int `yaml:"port_relay,omitempty" json:"port_relay,omitempty"`

	Secret []LabelSecretEntry `yaml:"secret,omitempty" json:"secret,omitempty"`

	EnvProvide map[string]string `yaml:"env_provide,omitempty" json:"env_provide,omitempty"`

	EnvRequire []EnvDependency `yaml:"env_require,omitempty" json:"env_require,omitempty"`

	EnvAccept []EnvDependency `yaml:"env_accept,omitempty" json:"env_accept,omitempty"`

	SecretRequire []EnvDependency `yaml:"secret_require,omitempty" json:"secret_require,omitempty"`

	SecretAccept []EnvDependency `yaml:"secret_accept,omitempty" json:"secret_accept,omitempty"`

	MCPProvide []CandyMCPProvide `yaml:"mcp_provide,omitempty" json:"mcp_provide,omitempty"`

	AgentProvide []AgentRuntimeCapability `yaml:"agent_provide,omitempty" json:"agent_provide,omitempty"`

	TerminalProfiles map[string]TerminalProfile `yaml:"terminal_profiles,omitempty" json:"terminal_profiles,omitempty"`

	MCPRequire []EnvDependency `yaml:"mcp_require,omitempty" json:"mcp_require,omitempty"`

	MCPAccept []EnvDependency `yaml:"mcp_accept,omitempty" json:"mcp_accept,omitempty"`

	Route []LabelRouteEntry `yaml:"route,omitempty" json:"route,omitempty"`

	EnvCandy map[string]string `yaml:"env_candy,omitempty" json:"env_candy,omitempty"`

	PathAppend []string `yaml:"path_append,omitempty" json:"path_append,omitempty"`

	Skill string `yaml:"skill,omitempty" json:"skill,omitempty"`

	Status string `yaml:"status,omitempty" json:"status,omitempty"`

	CheckLevel string `yaml:"check_level,omitempty" json:"check_level,omitempty"`

	Info string `yaml:"info,omitempty" json:"info,omitempty"`

	CandyVersion map[string]string `yaml:"candy_version,omitempty" json:"candy_version,omitempty"`

	DataEntries []LabelDataEntry `yaml:"data_entries,omitempty" json:"data_entries,omitempty"`

	DataImage bool `yaml:"data_image,omitempty" json:"data_image,omitempty"`
}

type BaseChainNode struct {
	Name string
	Img  BoxConfig
}

type BaseUser struct {
	Name string `yaml:"name,omitempty" json:"name"`

	UID int `yaml:"uid,omitempty" json:"uid"`

	GID int `yaml:"gid,omitempty" json:"gid"`

	Home string `yaml:"home,omitempty" json:"home"`
}

type Bootloader struct {
	InstallTemplate string `yaml:"install_template,omitempty" json:"install_template,omitempty"`

	InitramfsTemplate string `yaml:"initramfs_template,omitempty" json:"initramfs_template,omitempty"`

	FstabTemplate string `yaml:"fstab_template,omitempty" json:"fstab_template,omitempty"`
}

type Bootstrap struct {
	InstallCmd string `yaml:"install_cmd,omitempty" json:"install_cmd"`

	Package []string `yaml:"package,omitempty" json:"package,omitempty"`

	CacheMount []CacheMount `yaml:"cache_mount,omitempty" json:"cache_mount,omitempty"`
}

type Box struct {
	Name EntityRef `yaml:"name,omitempty" json:"name,omitempty"`

	Version CalVer `yaml:"version,omitempty" json:"version,omitempty"`

	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`

	Base string `yaml:"base,omitempty" json:"base,omitempty"`

	From string `yaml:"from,omitempty" json:"from,omitempty"`

	BootstrapBuilderImage string `yaml:"bootstrap_builder_image,omitempty" json:"bootstrap_builder_image,omitempty"`

	Platforms []string `yaml:"platform,omitempty" json:"platform,omitempty"`

	Tag string `yaml:"tag,omitempty" json:"tag,omitempty"`

	Registry string `yaml:"registry,omitempty" json:"registry,omitempty"`

	Distro []string `yaml:"distro,omitempty" json:"distro,omitempty"`

	// BuildFormats: a scalar OR a list on the wire (#BuildFormats UnmarshalYAML
	// normalizes "rpm" → ["rpm"]); the Go field is []string. gengotypes degrades
	// the disjunction to `any`, so pin the Go shape explicitly (the typed enum is
	// a future enhancement — collapse for now).
	Build []string `yaml:"build,omitempty" json:"build,omitempty"`

	Candy []CandyRef `yaml:"candy,omitempty" json:"candy,omitempty"`

	User string `yaml:"user,omitempty" json:"user,omitempty"`

	UID *int `yaml:"uid,omitempty" json:"uid,omitempty"`

	GID *int `yaml:"gid,omitempty" json:"gid,omitempty"`

	UserPolicy string `yaml:"user_policy,omitempty" json:"user_policy,omitempty"`

	Builder map[string]string `yaml:"builder,omitempty" json:"builder,omitempty"`

	Produce []BuildType `yaml:"produce,omitempty" json:"produce,omitempty"`

	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`

	EnvFile string `yaml:"env_file,omitempty" json:"env_file,omitempty"`

	Security *Security `yaml:"security,omitempty" json:"security,omitempty"`

	Network string `yaml:"network,omitempty" json:"network,omitempty"`

	Init string `yaml:"init,omitempty" json:"init,omitempty"`

	DataImage bool `yaml:"data_image,omitempty" json:"data_image,omitempty"`

	Bootc bool `yaml:"bootc,omitempty" json:"bootc,omitempty"`

	Readiness *Readiness `yaml:"readiness,omitempty" json:"readiness,omitempty"`

	Jobs *int `yaml:"jobs,omitempty" json:"jobs,omitempty"`

	PodmanJobs *int `yaml:"podman_jobs,omitempty" json:"podman_jobs,omitempty"`

	PodmanJobsCap *int `yaml:"podman_jobs_cap,omitempty" json:"podman_jobs_cap,omitempty"`

	ContextIgnore []string `yaml:"context_ignore,omitempty" json:"context_ignore,omitempty"`

	Cache string `yaml:"cache,omitempty" json:"cache,omitempty"`

	KeepImages *int `yaml:"keep_images,omitempty" json:"keep_images,omitempty"`

	KeepCheckRuns *int `yaml:"keep_check_runs,omitempty" json:"keep_check_runs,omitempty"`

	Merge *BoxMerge `yaml:"merge,omitempty" json:"merge,omitempty"`

	Alias []BoxAlias `yaml:"alias,omitempty" json:"alias,omitempty"`

	Plan []Step `yaml:"plan,omitempty" json:"plan,omitempty"`

	CheckLevel string `yaml:"check_level,omitempty" json:"check_level,omitempty"`

	Shell *Shell `yaml:"shell,omitempty" json:"shell,omitempty"`
}

type BoxAlias struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Command string `yaml:"command,omitempty" json:"command,omitempty"`
}

type BoxConfig = Box

type BoxFetchResolveReply struct {
	Path string `yaml:"path,omitempty" json:"path,omitempty"`
}

type BoxFetchResolveRequest struct {
	Spec string `yaml:"spec,omitempty" json:"spec"`

	Refresh bool `yaml:"refresh,omitempty" json:"refresh,omitempty"`
}

type BoxMap = map[string]json.RawMessage

type BoxMerge struct {
	Auto bool `yaml:"auto,omitempty" json:"auto,omitempty"`

	MaxMB int `yaml:"max_mb,omitempty" json:"max_mb,omitempty"`

	MaxTotalMB int `yaml:"max_total_mb,omitempty" json:"max_total_mb,omitempty"`
}

type BoxMetadata struct {
	Box string `yaml:"box,omitempty" json:"box,omitempty"`

	Version string `yaml:"version,omitempty" json:"version,omitempty"`

	Registry string `yaml:"registry,omitempty" json:"registry,omitempty"`

	Bootc bool `yaml:"bootc,omitempty" json:"bootc,omitempty"`

	UID int `yaml:"uid,omitempty" json:"uid,omitempty"`

	GID int `yaml:"gid,omitempty" json:"gid,omitempty"`

	User string `yaml:"user,omitempty" json:"user,omitempty"`

	Home string `yaml:"home,omitempty" json:"home,omitempty"`

	Port []string `yaml:"port,omitempty" json:"port,omitempty"`

	Volume []VolumeMount `yaml:"volume,omitempty" json:"volume,omitempty"`

	Alias []CollectedAlias `yaml:"alias,omitempty" json:"alias,omitempty"`

	Security Security `yaml:"security,omitempty" json:"security,omitempty"`

	Network string `yaml:"network,omitempty" json:"network,omitempty"`

	Tunnel *TunnelYAML `yaml:"tunnel,omitempty" json:"tunnel,omitempty"`

	DNS string `yaml:"dns,omitempty" json:"dns,omitempty"`

	AcmeEmail string `yaml:"acme_email,omitempty" json:"acme_email,omitempty"`

	Env []string `yaml:"env,omitempty" json:"env,omitempty"`

	Hook *CandyHook `yaml:"hook,omitempty" json:"hook,omitempty"`

	Route []LabelRouteEntry `yaml:"route,omitempty" json:"route,omitempty"`

	Init string `yaml:"init,omitempty" json:"init,omitempty"`

	InitDef *CapabilityInitDef `yaml:"init_def,omitempty" json:"init_def,omitempty"`

	Service []CapabilityService `yaml:"service,omitempty" json:"service,omitempty"`

	ServiceNames []string `yaml:"service_names,omitempty" json:"service_names,omitempty"`

	EnvCandy map[string]string `yaml:"env_candy,omitempty" json:"env_candy,omitempty"`

	PathAppend []string `yaml:"path_append,omitempty" json:"path_append,omitempty"`

	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`

	PortProto map[string]string `yaml:"port_proto,omitempty" json:"port_proto,omitempty"`

	PortRelay []int `yaml:"port_relay,omitempty" json:"port_relay,omitempty"`

	Skill string `yaml:"skill,omitempty" json:"skill,omitempty"`

	Status string `yaml:"status,omitempty" json:"status,omitempty"`

	Info string `yaml:"info,omitempty" json:"info,omitempty"`

	CandyVersion map[string]string `yaml:"candy_version,omitempty" json:"candy_version,omitempty"`

	Secret []LabelSecretEntry `yaml:"secret,omitempty" json:"secret,omitempty"`

	Distro []string `yaml:"distro,omitempty" json:"distro,omitempty"`

	BuildFormat []string `yaml:"build_format,omitempty" json:"build_format,omitempty"`

	Builder map[string]string `yaml:"builder,omitempty" json:"builder,omitempty"`

	Build []string `yaml:"build,omitempty" json:"build,omitempty"`

	DataEntries []LabelDataEntry `yaml:"data_entries,omitempty" json:"data_entries,omitempty"`

	DataImage bool `yaml:"data_image,omitempty" json:"data_image,omitempty"`

	EnvProvide map[string]string `yaml:"env_provide,omitempty" json:"env_provide,omitempty"`

	EnvRequire []EnvDependency `yaml:"env_require,omitempty" json:"env_require,omitempty"`

	EnvAccept []EnvDependency `yaml:"env_accept,omitempty" json:"env_accept,omitempty"`

	SecretAccept []EnvDependency `yaml:"secret_accept,omitempty" json:"secret_accept,omitempty"`

	SecretRequire []EnvDependency `yaml:"secret_require,omitempty" json:"secret_require,omitempty"`

	MCPProvide []CandyMCPProvide `yaml:"mcp_provide,omitempty" json:"mcp_provide,omitempty"`

	AgentProvide []AgentRuntimeCapability `yaml:"agent_provide,omitempty" json:"agent_provide,omitempty"`

	TerminalProfiles map[string]TerminalProfile `yaml:"terminal_profiles,omitempty" json:"terminal_profiles,omitempty"`

	MCPRequire []EnvDependency `yaml:"mcp_require,omitempty" json:"mcp_require,omitempty"`

	MCPAccept []EnvDependency `yaml:"mcp_accept,omitempty" json:"mcp_accept,omitempty"`

	Description *LabelDescriptionSet `yaml:"description,omitempty" json:"description,omitempty"`

	Shell *LabelShellSet `yaml:"shell,omitempty" json:"shell,omitempty"`

	CheckLevel string `yaml:"check_level,omitempty" json:"check_level,omitempty"`
}

type BoxRefResolveReply struct {
	// exists_ref / pull_ref is the fully-qualified registry ref to check for local
	// presence / hand to `podman pull`; "" when the identifier could not be
	// resolved (no project reachable, or an unknown short name).
	ExistsRef string `yaml:"exists_ref,omitempty" json:"exists_ref,omitempty"`

	PullRef string `yaml:"pull_ref,omitempty" json:"pull_ref,omitempty"`

	// build_fallback_short is the short name (bare or namespace-qualified, e.g.
	// "fedora.fedora-builder") `charly box build` should target when the pull
	// fails; "" when no local build-fallback is possible for this identifier.
	BuildFallbackShort string `yaml:"build_fallback_short,omitempty" json:"build_fallback_short,omitempty"`

	// produced_ref is the registry ref build_fallback_short resolves to today
	// (registry+name, tag-less) — used to tag-alias a pinned-tag input ref onto
	// the freshly built image.
	ProducedRef string `yaml:"produced_ref,omitempty" json:"produced_ref,omitempty"`
}

type BoxRefResolveRequest struct {
	Image string `yaml:"image,omitempty" json:"image"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`
}

type BuildEngineScanRemoteRequest struct {
	CacheDir string `yaml:"cache_dir,omitempty" json:"cache_dir"`

	RepoPath string `yaml:"repo_path,omitempty" json:"repo_path"`

	Refs []string `yaml:"refs,omitempty" json:"refs,omitempty"`
}

type BuildEnsureReply struct {
	Error string `yaml:"error,omitempty" json:"error,omitempty"`
}

type BuildEnsureRequest struct {
	Image string `yaml:"image,omitempty" json:"image"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`

	BuildEngine string `yaml:"build_engine,omitempty" json:"build_engine,omitempty"`

	RunEngine string `yaml:"run_engine,omitempty" json:"run_engine,omitempty"`
}

type BuildEnv struct {
	Distros []string `yaml:"distros,omitempty" json:"distros,omitempty"`

	Image string `yaml:"image,omitempty" json:"image,omitempty"`

	DevLocalPkg bool `yaml:"dev_local_pkg,omitempty" json:"dev_local_pkg,omitempty"`

	ImageBuildDir string `yaml:"image_build_dir,omitempty" json:"image_build_dir,omitempty"`

	ContextRelPrefix string `yaml:"context_rel_prefix,omitempty" json:"context_rel_prefix,omitempty"`

	// A pod-overlay deploy's add_candy: refs (if any) — threaded so a HOST-COUPLED word's OpEmit
	// (candy/plugin-installstep's getGenerator) can widen ITS OWN "resolved-project" envelope
	// re-fetch the same way ScanAllCandyWithConfigOpts' ResolveOpts.ExtraCandyRefs already widens
	// the host's own overlay Generator (hostBuildOverlay). Without this, an add_candy candy the
	// overlay build correctly resolved host-side is absent from this plugin's INDEPENDENT
	// envelope fetch, and candyByName's REMOTE-candy fallback still misses (RCA'd K1-alpha
	// regression: check-addcandy-pod's overlay-deploy path, "candy not found").
	ExtraCandyRefs []string `yaml:"extra_candy_refs,omitempty" json:"extra_candy_refs,omitempty"`
}

type BuildFormat = string

type BuildPkgReply struct {
	Written []string `yaml:"written,omitempty" json:"written,omitempty"`

	Error string `yaml:"error,omitempty" json:"error,omitempty"`
}

type BuildPkgRequest struct {
	Format []string `yaml:"format,omitempty" json:"format,omitempty"`

	Candy string `yaml:"candy,omitempty" json:"candy,omitempty"`

	Out string `yaml:"out,omitempty" json:"out,omitempty"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`
}

type BuildReply struct {
	Written []string `yaml:"written,omitempty" json:"written,omitempty"`

	Error string `yaml:"error,omitempty" json:"error,omitempty"`
}

type BuildRequest struct {
	Boxes []string `yaml:"boxes,omitempty" json:"boxes,omitempty"`

	Tag string `yaml:"tag,omitempty" json:"tag,omitempty"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`

	IncludeDisabled bool `yaml:"include_disabled,omitempty" json:"include_disabled,omitempty"`

	DevLocalPkg bool `yaml:"dev_local_pkg,omitempty" json:"dev_local_pkg,omitempty"`

	Push bool `yaml:"push,omitempty" json:"push,omitempty"`

	Platform string `yaml:"platform,omitempty" json:"platform,omitempty"`

	Cache string `yaml:"cache,omitempty" json:"cache,omitempty"`

	NoCache bool `yaml:"no_cache,omitempty" json:"no_cache,omitempty"`

	Jobs int `yaml:"jobs,omitempty" json:"jobs,omitempty"`

	PodmanJobs int `yaml:"podman_jobs,omitempty" json:"podman_jobs,omitempty"`
}

type BuildResolveBox struct {
	Name string `yaml:"name,omitempty" json:"name"`

	FullTag string `yaml:"full_tag,omitempty" json:"full_tag,omitempty"`

	Registry string `yaml:"registry,omitempty" json:"registry,omitempty"`

	Platforms []string `yaml:"platforms,omitempty" json:"platforms,omitempty"`

	MergeAuto bool `yaml:"merge_auto,omitempty" json:"merge_auto,omitempty"`

	MergeMaxMB int64 `yaml:"merge_max_mb,omitempty" json:"merge_max_mb,omitempty"`

	MergeMaxTotalMB int64 `yaml:"merge_max_total_mb,omitempty" json:"merge_max_total_mb,omitempty"`

	// from/bootstrap_builder_image/distro_def/bootstrap_builder are the privileged-bootstrap
	// inputs (a `from: builder:<name>` image) the candy needs to run
	// buildkit.RunPrivileged itself instead of the host doing it in the build-prep seam.
	// bootstrap_builder is the SPECIFIC resolved #Builder for `from`'s builder name (not the
	// whole per-image builder map) — the minimal slice runPrivilegedBootstrap actually reads.
	// Both nil/empty for a non-bootstrap image (the common case).
	From string `yaml:"from,omitempty" json:"from,omitempty"`

	BootstrapBuilderImage string `yaml:"bootstrap_builder_image,omitempty" json:"bootstrap_builder_image,omitempty"`

	DistroDef *ResolvedDistro `yaml:"distro_def,omitempty" json:"distro_def,omitempty"`

	BootstrapBuilder *Builder `yaml:"bootstrap_builder,omitempty" json:"bootstrap_builder,omitempty"`
}

type BuildResolveReply struct {
	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`

	EngineName string `yaml:"engine_name,omitempty" json:"engine_name,omitempty"`

	Platform string `yaml:"platform,omitempty" json:"platform,omitempty"`

	Order []string `yaml:"order,omitempty" json:"order,omitempty"`

	Levels [][]string `yaml:"levels,omitempty" json:"levels,omitempty"`

	Boxes []BuildResolveBox `yaml:"boxes,omitempty" json:"boxes,omitempty"`

	Jobs int64 `yaml:"jobs,omitempty" json:"jobs,omitempty"`

	PodmanJobs int64 `yaml:"podman_jobs,omitempty" json:"podman_jobs,omitempty"`

	Cache string `yaml:"cache,omitempty" json:"cache,omitempty"`

	KeepImages int64 `yaml:"keep_images,omitempty" json:"keep_images,omitempty"`

	Written []string `yaml:"written,omitempty" json:"written,omitempty"`

	// resolved_project — the full resolved-project envelope with build-render
	// caches (BakedMetadata/RenderCandyOrder/InitSystem/InitDef/ActiveInits/Caps
	// on each ResolvedBoxView + GlobalOrder/ExternalizedBuilders on the project),
	// so plugin-build renders Containerfiles via deploykit.Generator WITHOUT the
	// live *Candy/*Config graph (#67 render-DRIVE move). Filled by the build-prep
	// seam (render-prep → projectResolvedProject with caches). Empty for the
	// generate-only path that writes Containerfiles host-side (transitional).
	ResolvedProject *ResolvedProject `yaml:"resolved_project,omitempty" json:"resolved_project,omitempty"`

	Error string `yaml:"error,omitempty" json:"error,omitempty"`
}

type BuildResolveRequest struct {
	Boxes []string `yaml:"boxes,omitempty" json:"boxes,omitempty"`

	Tag string `yaml:"tag,omitempty" json:"tag,omitempty"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`

	IncludeDisabled bool `yaml:"include_disabled,omitempty" json:"include_disabled,omitempty"`

	DevLocalPkg bool `yaml:"dev_local_pkg,omitempty" json:"dev_local_pkg,omitempty"`

	Push bool `yaml:"push,omitempty" json:"push,omitempty"`

	Platform string `yaml:"platform,omitempty" json:"platform,omitempty"`

	Cache string `yaml:"cache,omitempty" json:"cache,omitempty"`

	NoCache bool `yaml:"no_cache,omitempty" json:"no_cache,omitempty"`

	Jobs int64 `yaml:"jobs,omitempty" json:"jobs,omitempty"`

	PodmanJobs int64 `yaml:"podman_jobs,omitempty" json:"podman_jobs,omitempty"`

	GenerateOnly bool `yaml:"generate_only,omitempty" json:"generate_only,omitempty"`
}

type BuildStageContext struct {
	BuilderRef string `yaml:"builder_ref,omitempty" json:"builder_ref,omitempty"`

	StageName string `yaml:"stage_name,omitempty" json:"stage_name,omitempty"`

	LayerStage string `yaml:"layer_stage,omitempty" json:"layer_stage,omitempty"`

	CopySrc string `yaml:"copy_src,omitempty" json:"copy_src,omitempty"`

	UID int `yaml:"uid,omitempty" json:"uid,omitempty"`

	GID int `yaml:"gid,omitempty" json:"gid,omitempty"`

	Home string `yaml:"home,omitempty" json:"home,omitempty"`

	User string `yaml:"user,omitempty" json:"user,omitempty"`

	Manifest string `yaml:"manifest,omitempty" json:"manifest,omitempty"`

	HasLockFile bool `yaml:"has_lock_file,omitempty" json:"has_lock_file,omitempty"`

	InstallCmd string `yaml:"install_cmd,omitempty" json:"install_cmd,omitempty"`

	ManylinuxFix string `yaml:"manylinux_fix,omitempty" json:"manylinux_fix,omitempty"`

	CacheMounts []CacheMount `yaml:"cache_mounts,omitempty" json:"cache_mounts,omitempty"`

	Packages []string `yaml:"packages,omitempty" json:"packages,omitempty"`

	Options []string `yaml:"options,omitempty" json:"options,omitempty"`

	HasBuildScript bool `yaml:"has_build_script,omitempty" json:"has_build_script,omitempty"`

	BuildScript string `yaml:"build_script,omitempty" json:"build_script,omitempty"`
}

type BuildTarget struct {
	Name string `yaml:"name,omitempty" json:"name,omitempty"`

	Auto bool `yaml:"auto,omitempty" json:"auto,omitempty"`
}

type BuildType = string

type Builder struct {
	DetectFiles []string `yaml:"detect_file,omitempty" json:"detect_file,omitempty"`

	DetectConfig string `yaml:"detect_config,omitempty" json:"detect_config,omitempty"`

	RequiresSrcDir bool `yaml:"requires_src_dir,omitempty" json:"requires_src_dir,omitempty"`

	Inline bool `yaml:"inline,omitempty" json:"inline,omitempty"`

	CacheMount []CacheMount `yaml:"cache_mount,omitempty" json:"cache_mount,omitempty"`

	Env StrMap `yaml:"env,omitempty" json:"env,omitempty"`

	RuntimeEnv StrMap `yaml:"runtime_env,omitempty" json:"runtime_env,omitempty"`

	InstallTemplate string `yaml:"install_template,omitempty" json:"install_template,omitempty"`

	ManylinuxFix string `yaml:"manylinux_fix,omitempty" json:"manylinux_fix,omitempty"`

	BuildScript string `yaml:"build_script,omitempty" json:"build_script,omitempty"`

	Phases *PhaseSet `yaml:"phase,omitempty" json:"phase,omitempty"`

	InstallCommands map[string]string `yaml:"install_command,omitempty" json:"install_command,omitempty"`

	CopyArtifacts []Copy `yaml:"copy_artifact,omitempty" json:"copy_artifact,omitempty"`

	CopyBinary *Copy `yaml:"copy_binary,omitempty" json:"copy_binary,omitempty"`

	PathContributions []string `yaml:"path_contribution,omitempty" json:"path_contribution,omitempty"`

	Kind string `yaml:"kind,omitempty" json:"kind"`

	Privileged bool `yaml:"privileged,omitempty" json:"privileged"`

	OutputArtifact string `yaml:"output_artifact,omitempty" json:"output_artifact,omitempty"`
}

type BuilderCollectInput struct {
	Candy string `yaml:"candy,omitempty" json:"candy"`

	Builder string `yaml:"builder,omitempty" json:"builder"`

	Home string `yaml:"home,omitempty" json:"home,omitempty"`

	Packages []string `yaml:"packages,omitempty" json:"packages,omitempty"`

	Replaces []string `yaml:"replaces,omitempty" json:"replaces,omitempty"`
}

type BuilderCollectReply struct {
	Context map[string]any `yaml:"context,omitempty" json:"context,omitempty"`
}

type BuilderDef = Builder

type BuilderMap map[string]string

type BuilderResolveInput struct {
	Candy string `yaml:"candy,omitempty" json:"candy"`

	Builder string `yaml:"builder,omitempty" json:"builder,omitempty"`

	BuilderRef string `yaml:"builder_ref,omitempty" json:"builder_ref,omitempty"`

	StageName string `yaml:"stage_name,omitempty" json:"stage_name,omitempty"`

	LayerStage string `yaml:"layer_stage,omitempty" json:"layer_stage,omitempty"`

	CopySrc string `yaml:"copy_src,omitempty" json:"copy_src,omitempty"`

	UID int `yaml:"uid,omitempty" json:"uid,omitempty"`

	GID int `yaml:"gid,omitempty" json:"gid,omitempty"`

	Home string `yaml:"home,omitempty" json:"home,omitempty"`

	User string `yaml:"user,omitempty" json:"user,omitempty"`

	Manifest string `yaml:"manifest,omitempty" json:"manifest,omitempty"`

	HasLockFile bool `yaml:"has_lock_file,omitempty" json:"has_lock_file,omitempty"`

	InstallCmd string `yaml:"install_cmd,omitempty" json:"install_cmd,omitempty"`

	ManylinuxFix string `yaml:"manylinux_fix,omitempty" json:"manylinux_fix,omitempty"`

	HasBuildScript bool `yaml:"has_build_script,omitempty" json:"has_build_script,omitempty"`

	BuildScript string `yaml:"build_script,omitempty" json:"build_script,omitempty"`

	Packages []string `yaml:"packages,omitempty" json:"packages,omitempty"`

	Options []string `yaml:"options,omitempty" json:"options,omitempty"`

	CacheMountsOwned string `yaml:"cache_mounts_owned,omitempty" json:"cache_mounts_owned,omitempty"`

	CacheMountsAuto string `yaml:"cache_mounts_auto,omitempty" json:"cache_mounts_auto,omitempty"`

	Inline bool `yaml:"inline,omitempty" json:"inline,omitempty"`
}

type BuilderResolveReply struct {
	Stage string `yaml:"stage,omitempty" json:"stage,omitempty"`

	CopyArtifacts []string `yaml:"copy_artifacts,omitempty" json:"copy_artifacts,omitempty"`

	CopyBinary string `yaml:"copy_binary,omitempty" json:"copy_binary,omitempty"`

	InlineFragment string `yaml:"inline_fragment,omitempty" json:"inline_fragment,omitempty"`
}

type BuilderReverseInput struct {
	Candy string `yaml:"candy,omitempty" json:"candy"`

	Builder string `yaml:"builder,omitempty" json:"builder"`

	Context map[string]any `yaml:"context,omitempty" json:"context,omitempty"`
}

type BuilderReverseReply struct {
	ReverseOps []ReverseOp `yaml:"reverse_ops,omitempty" json:"reverse_ops,omitempty"`
}

type BuilderRunOpts struct {
	Engine       string // "podman" or "docker"; default "podman"
	BuilderImage string // full image ref, e.g. "ghcr.io/opencharly/fedora-builder:latest"
	CandyDir     string // absolute path to candy source (bind-mounted as /work)
	ScriptBody   string // shell script contents to pass to bash -c

	// ResolveImage + EnsureImage inject the image-presence behavior that used to
	// read *Config directly (Config stays a charly kernel type; the executor is an
	// sdk mechanism reached through this seam). ResolveImage maps a short/namespaced
	// builder ref to its concrete podman storage key (side-effect-free — safe in the
	// dry-run path). EnsureImage guarantees the image is present, falling back to a
	// local `charly box build <basename>` when it is project-buildable. The charly
	// callers close over Cfg + ProjectDir; see charly/host_build_box_ref_resolve.go
	// (ResolveImage) and charly/dispatch_build_ensure.go (EnsureImage).
	ResolveImage func(image string) (string, error)
	EnsureImage  func(ctx context.Context, image string) error

	// Bind-mounts. Keys are container paths; values are host paths.
	// Set by the caller based on the builder kind — pixi/npm/cargo use
	// the same HOME-subdir layout, aur uses a tmpdir for /tmp/aur-pkgs.
	BindMounts map[string]string

	// Env vars to set inside the container (in addition to HOME).
	Env map[string]string

	// HostHome is the invoking user's absolute home dir. Set via HOME=
	// inside the container so path-baking (pixi shebangs, etc.) resolves
	// to a path that's valid both inside (via bind-mount) and outside.
	HostHome string

	// DryRun returns the command line that would run without executing.
	// Used for --dry-run deploy.
	DryRun bool

	// RunAsRoot spawns the container as UID 0 instead of the host's
	// UID. Needed for builders whose script body uses `sudo` against
	// users that don't exist in the builder image's /etc/passwd —
	// e.g. AUR's makepkg+yay flow inside a non-OCI-staged builder
	// image. Under rootless podman, root-in-container maps to the
	// host's UID, so file ownership in bind-mounts stays correct.
	RunAsRoot bool
}

type BundleNode = Deploy

type CLIArg struct {
	Prop string `yaml:"prop,omitempty" json:"prop"`

	Name string `yaml:"name,omitempty" json:"name"`

	Type string `yaml:"type,omitempty" json:"type"`

	Help string `yaml:"help,omitempty" json:"help,omitempty"`

	Enum []string `yaml:"enum,omitempty" json:"enum,omitempty"`

	Default string `yaml:"default,omitempty" json:"default,omitempty"`

	HasDefault bool `yaml:"has_default,omitempty" json:"has_default,omitempty"`

	Required bool `yaml:"required,omitempty" json:"required,omitempty"`

	IsBool bool `yaml:"is_bool,omitempty" json:"is_bool,omitempty"`

	IsSlice bool `yaml:"is_slice,omitempty" json:"is_slice,omitempty"`

	IsMap bool `yaml:"is_map,omitempty" json:"is_map,omitempty"`

	Negated bool `yaml:"negated,omitempty" json:"negated,omitempty"`

	ElemType string `yaml:"elem_type,omitempty" json:"elem_type,omitempty"`
}

type CLILeaf struct {
	Path string `yaml:"path,omitempty" json:"path"`

	Help string `yaml:"help,omitempty" json:"help,omitempty"`

	Hidden bool `yaml:"hidden,omitempty" json:"hidden,omitempty"`

	Positionals []CLIArg `yaml:"positionals,omitempty" json:"positionals,omitempty"`

	Flags []CLIArg `yaml:"flags,omitempty" json:"flags,omitempty"`
}

type CLIModel struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Version string `yaml:"version,omitempty" json:"version"`

	Leaves []CLILeaf `yaml:"leaves,omitempty" json:"leaves"`
}

type CacheMount struct {
	Dst string `yaml:"dst,omitempty" json:"dst"`

	Sharing string `yaml:"sharing,omitempty" json:"sharing,omitempty"`

	Owned bool `yaml:"owned,omitempty" json:"owned,omitempty"`
}

type CacheMountView struct {
	Dst string `yaml:"dst,omitempty" json:"dst,omitempty"`

	Sharing string `yaml:"sharing,omitempty" json:"sharing,omitempty"`
}

type CalVer = string

type Candy struct {
	// --- identity (required: ADE mandates version+name+description+plan) ---
	Version CalVer `yaml:"version,omitempty" json:"version"`

	Name EntityRef `yaml:"name,omitempty" json:"name,omitempty"`

	Description string `yaml:"description,omitempty" json:"description"`

	Plan []Step `yaml:"plan,omitempty" json:"plan,omitempty"`

	// --- maturity / engine ---
	Status string `yaml:"status,omitempty" json:"status,omitempty"`

	// engine — a candy's required run engine; per-image resolution walks the
	// candy chain (engine.go ResolveBoxEngine) and cross-candy conflicts are a
	// validate error. RETAINED by the schema-compaction consumer audit.
	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`

	// `from:` is NOT a candy field — EDGE-INHERIT cutover D: a candy: node carrying
	// `base:` or `from:` is a full IMAGE (#Box, the former box:), routed there by the
	// loader; a LAYER fragment has neither. So `from:` lives only on #Box.
	Reboot bool `yaml:"reboot,omitempty" json:"reboot,omitempty"`

	// --- composition ---
	Candy []CandyRef `yaml:"candy,omitempty" json:"candy,omitempty"`

	Require []CandyRef `yaml:"require,omitempty" json:"require,omitempty"`

	// bake_plugin — the OUT-OF-TREE plugin candies whose pre-built provider binary
	// this candy BAKES into every composing image at /usr/lib/charly/plugins/, so a
	// DEPLOYED container (no candy source, no go toolchain) can run an external plugin
	// its in-container charly needs at runtime — e.g. charly-mcp bakes plugin-mcp so
	// `charly mcp serve` resolves the external `mcp` command in-container. The S0
	// baked-plugin BUILD-side seam, the deploy-time counterpart of resolvePluginBinary's
	// bakedPluginBinary fallback (plugin_loader.go). See generate.go emitBakedPlugins.
	BakePlugin []CandyRef `yaml:"bake_plugin,omitempty" json:"bake_plugin,omitempty"`

	RequiresCapability []string `yaml:"requires_capability,omitempty" json:"requires_capability,omitempty"`

	Capability *CandyCapability `yaml:"capability,omitempty" json:"capability,omitempty"`

	// plugin — declaring this block makes the candy a PLUGIN: it provides
	// reserved-word Providers (built-in OR out-of-tree). The candy is otherwise
	// authored, validated, built, deployed, and checked like any candy (R3 — one
	// authoring surface). See provider.go / plugin_loader.go.
	Plugin *Plugin `yaml:"plugin,omitempty" json:"plugin,omitempty"`

	// external_builder — the reserved word of an EXTERNAL builder plugin
	// (`builder:<word>`, an out-of-tree grpcProvider) this candy SELECTS to produce
	// a multi-stage build artifact. At image build the generator resolves the word,
	// Invokes the provider's OpResolve, and splices the returned BuilderResolveReply
	// (the FROM…AS stage pre-main-FROM + the COPY --from artifacts post-main-FROM).
	// The build-time BUILDER leg — the counterpart of a `run:` step's `plugin:` verb
	// (the STEP leg). A builtin builder (pixi/cargo/npm/aur) is selected by detection
	// files, NOT this field. See generate.go emitExternalBuilderStages.
	ExternalBuilder string `yaml:"external_builder,omitempty" json:"external_builder,omitempty"`

	// --- runtime env / local vars / PATH ---
	// env forbids PATH (validate.go: use path_append instead). Values are
	// Go-coerced scalars (#StrVal) — an unquoted `PORT: 8080` is a string. The Go
	// field is map[string]string (yaml.v3 coerces the scalar), so pin the shape
	// (gengotypes degrades the #StrVal value to `any`).
	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`

	// var: Go field is `Vars map[string]string`; gengotypes degrades the
	// pattern-keyed map to an empty struct, so pin name + shape.
	Vars map[string]string `yaml:"var,omitempty" json:"var,omitempty"`

	PathAppend []string `yaml:"path_append,omitempty" json:"path_append,omitempty"`

	// --- package surface (Calamares-aligned) ---
	Package []PackageItem `yaml:"package,omitempty" json:"package,omitempty"`

	Distro map[string]*DistroPackages `yaml:"distro,omitempty" json:"distro,omitempty"`

	Apk []ApkPackageSpec `yaml:"apk,omitempty" json:"apk,omitempty"`

	// localpkg maps a native package FORMAT to a bundled source dir; a scalar
	// form is rejected by Go. Closed to the three known formats.
	// localpkg Go field is `LocalPkg map[string]string` (a per-format → source-dir
	// map); pin name + shape (gengotypes would emit an inline struct named
	// `Localpkg`).
	LocalPkg map[string]string `yaml:"localpkg,omitempty" json:"localpkg,omitempty"`

	// --- networking / routing ---
	// PortSpec: a plain int OR a "proto:port" string (proto ∈ http/https/tcp/…);
	// the Go normalizer canonicalizes either form to the {port, protocol}
	// PortSpec struct, so the Go field is []PortSpec (gengotypes degrades the
	// scalar|string disjunction element to `any`).
	Port []PortSpec `yaml:"port,omitempty" json:"port,omitempty"`

	PortRelay []int `yaml:"port_relay,omitempty" json:"port_relay,omitempty"`

	Route *CandyRoute `yaml:"route,omitempty" json:"route,omitempty"`

	// --- services / volumes / aliases / extract / data ---
	Service []CandyService `yaml:"service,omitempty" json:"service,omitempty"`

	Volume []CandyVolume `yaml:"volume,omitempty" json:"volume,omitempty"`

	Alias []CandyAlias `yaml:"alias,omitempty" json:"alias,omitempty"`

	Extract []CandyExtract `yaml:"extract,omitempty" json:"extract,omitempty"`

	Data []CandyData `yaml:"data,omitempty" json:"data,omitempty"`

	// --- security / hooks ---
	// (the candy-level `libvirt:` raw-XML-snippet field was removed — zero live Go
	// consumers, retired alongside the box-level libvirt hard-cutover; migrated
	// away by candy/plugin-migrate's stripCandyLibvirtField. The paired `kind: vm`
	// entity's OWN `libvirt: {...}` domain config, sdk/schema/vm.cue #Vm.libvirt,
	// is unrelated and unaffected.)
	Security *Security `yaml:"security,omitempty" json:"security,omitempty"`

	Hook *CandyHook `yaml:"hook,omitempty" json:"hook,omitempty"`

	// --- env/secret/mcp dependency + provides surface ---
	// All six env/secret/mcp dependency lists decode into the ONE Go type
	// []EnvDependency (pinned via @go(...,type=[]EnvDependency)); the per-context
	// CUE refinements (env-var name regex; the charly/ secret-key prefix) only
	// TIGHTEN validation — they don't change the emitted Go type (an inline
	// `#EnvDependency & {…}` would otherwise make gengotypes emit an anonymous
	// struct). mcp_* keep the base shape (an MCP server name is not env-var-
	// constrained).
	EnvProvides StrMap `yaml:"env_provide,omitempty" json:"env_provide,omitempty"`

	EnvRequire []EnvDependency `yaml:"env_require,omitempty" json:"env_require,omitempty"`

	EnvAccept []EnvDependency `yaml:"env_accept,omitempty" json:"env_accept,omitempty"`

	SecretAccept []EnvDependency `yaml:"secret_accept,omitempty" json:"secret_accept,omitempty"`

	SecretRequire []EnvDependency `yaml:"secret_require,omitempty" json:"secret_require,omitempty"`

	MCPProvide []CandyMCPProvide `yaml:"mcp_provide,omitempty" json:"mcp_provide,omitempty"`

	AgentProvide []AgentRuntimeCapability `yaml:"agent_provide,omitempty" json:"agent_provide,omitempty"`

	// terminal_profile keeps the authored-key convention: every collection-
	// holding authored key in this block is singular (env_provide, mcp_provide,
	// agent_provide, …). The baked wire/label shape is the PLURAL
	// `terminal_profiles` (schema/boxmetadata.cue; spec.LabelTerminalProfiles
	// "ai.opencharly.terminal_profiles") — a key burned into built images, so
	// the singular-authored ↔ plural-wire mapping is deliberate and stable,
	// not a typo to "align" (renaming either side is a format change).
	TerminalProfiles map[string]TerminalProfile `yaml:"terminal_profile,omitempty" json:"terminal_profile,omitempty"`

	MCPRequire []EnvDependency `yaml:"mcp_require,omitempty" json:"mcp_require,omitempty"`

	MCPAccept []EnvDependency `yaml:"mcp_accept,omitempty" json:"mcp_accept,omitempty"`

	SecretYAML []CandySecret `yaml:"secret,omitempty" json:"secret,omitempty"`

	// --- shell init (same shape as box shell) ---
	Shell *Shell `yaml:"shell,omitempty" json:"shell,omitempty"`

	// --- operator-facing artifacts ---
	Artifact []CandyArtifact `yaml:"artifact,omitempty" json:"artifact,omitempty"`
}

type CandyAlias struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Command string `yaml:"command,omitempty" json:"command"`
}

type CandyArtifact struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Path string `yaml:"path,omitempty" json:"path"`

	RetrieveTo string `yaml:"retrieve_to,omitempty" json:"retrieve_to"`

	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`

	Optional bool `yaml:"optional,omitempty" json:"optional,omitempty"`

	WaitSeconds int `yaml:"wait_second,omitempty" json:"wait_second,omitempty"`

	Rewrite []CandyArtifactRewrite `yaml:"rewrite,omitempty" json:"rewrite,omitempty"`

	// register: an optional NAME-BLIND post-retrieve processing hint (e.g. "kubeconfig") —
	// what to do with the retrieved artifact beyond the generic retrieve/rewrite pipeline,
	// dispatched by a host-side registry keyed on this word (retrieveArtifactsAndK3s /
	// artifactRegisterHandlers). Replaces a hardcoded candy-NAME check
	// (deployHasCandy(candyList, "k3s-server")) with a declaration the candy itself carries,
	// so a future candy needing the same registration need not be named "k3s-server".
	Register string `yaml:"register,omitempty" json:"register,omitempty"`
}

type CandyArtifactRewrite struct {
	Find string `yaml:"find,omitempty" json:"find"`

	Replace string `yaml:"replace,omitempty" json:"replace,omitempty"`
}

type CandyCandidate struct {
	Scanned ScannedCandy
	Version string // per-entity version (Scanned.Model.Version) — mandatory, never ""
	GitTag  string // fetch coordinate (the @github :vTAG)
	Source  string // "<repo>@<git-tag>" for warning attribution
}

type CandyCapabilities = CandyCapability

type CandyCapabilitiesView struct {
	PreserveUser bool `yaml:"preserve_user,omitempty" json:"preserve_user,omitempty"`
}

type CandyCapability struct {
	PreserveUser bool `yaml:"preserve_user,omitempty" json:"preserve_user,omitempty"`

	NeedsRootAfterInit bool `yaml:"needs_root_after_init,omitempty" json:"needs_root_after_init,omitempty"`

	InitSystemHint string `yaml:"init_system_hint,omitempty" json:"init_system_hint,omitempty"`

	DataOnly bool `yaml:"data_only,omitempty" json:"data_only,omitempty"`

	OCILabels map[string]string `yaml:"oci_label,omitempty" json:"oci_label,omitempty"`
}

type CandyData struct {
	Src string `yaml:"src,omitempty" json:"src"`

	Volume string `yaml:"volume,omitempty" json:"volume"`

	Dest string `yaml:"dest,omitempty" json:"dest,omitempty"`
}

type CandyExtract struct {
	Source string `yaml:"source,omitempty" json:"source"`

	Path string `yaml:"path,omitempty" json:"path"`

	Dest string `yaml:"dest,omitempty" json:"dest"`
}

type CandyHook struct {
	PostEnable string `yaml:"post_enable,omitempty" json:"post_enable,omitempty"`

	PreRemove string `yaml:"pre_remove,omitempty" json:"pre_remove,omitempty"`
}

type CandyMCPProvide struct {
	Name string `yaml:"name,omitempty" json:"name"`

	URL string `yaml:"url,omitempty" json:"url"`

	Transport string `yaml:"transport,omitempty" json:"transport,omitempty"`
}

type CandyModel struct {
	// --- identity ---
	Name string `yaml:"name,omitempty" json:"name,omitempty"`

	Version string `yaml:"version,omitempty" json:"version,omitempty"`

	SourceDir string `yaml:"source_dir,omitempty" json:"source_dir,omitempty"`

	Reboot bool `yaml:"reboot,omitempty" json:"reboot,omitempty"`

	// --- host-precomputed predicates (#67 render-DRIVE move) ---
	// has_content / has_install_files are the LIVE *Candy.HasContent() / HasInstallFiles()
	// verdicts, computed HOST-SIDE (the live Candy has the env/ports/route/volumes/aliases/
	// libvirt/init fields + the fs-probe caches the envelope CandyModel cannot recompute
	// faithfully) and carried here so the specCandyAdapter matches the live *Candy
	// byte-exactly — the candy-graph composition (ExpandCandy/ResolveCandyOrder: a composing
	// candy with no content is skipped) and the pixi-bound intermediate detection both gate
	// on these. A pure-composition candy (e.g. agent-forwarding: candy: [gnupg,direnv,
	// ssh-client], only a check plan) has has_content=false, so it is correctly EXCLUDED
	// from the candy graph — matching the pre-move core render.
	HasContent bool `yaml:"has_content,omitempty" json:"has_content,omitempty"`

	HasInstallFiles bool `yaml:"has_install_files,omitempty" json:"has_install_files,omitempty"`

	// --- plan + lowered ops ---
	Plan []Step `yaml:"plan,omitempty" json:"plan,omitempty"`

	RunOps []Op `yaml:"run_ops,omitempty" json:"run_ops,omitempty"`

	// --- services / extract / data / apk ---
	Service []CandyService `yaml:"service,omitempty" json:"service,omitempty"`

	Extract []CandyExtract `yaml:"extract,omitempty" json:"extract,omitempty"`

	Data []CandyData `yaml:"data,omitempty" json:"data,omitempty"`

	Apk []ApkPackageSpec `yaml:"apk,omitempty" json:"apk,omitempty"`

	// --- package surface (resolved) ---
	TopPackages []string `yaml:"top_packages,omitempty" json:"top_packages,omitempty"`

	LocalPkg map[string]string `yaml:"localpkg,omitempty" json:"localpkg,omitempty"`

	FormatSections map[string]PackageSection `yaml:"format_sections,omitempty" json:"format_sections,omitempty"`

	TagSections map[string]TagPkgConfig `yaml:"tag_sections,omitempty" json:"tag_sections,omitempty"`

	// --- env / vars / route / shell ---
	Vars map[string]string `yaml:"vars,omitempty" json:"vars,omitempty"`

	Env *EnvConfig `yaml:"env,omitempty" json:"env,omitempty"`

	Route *RouteConfig `yaml:"route,omitempty" json:"route,omitempty"`

	Shell *Shell `yaml:"shell,omitempty" json:"shell,omitempty"`

	// --- volumes / aliases ---
	Volumes []CandyVolume `yaml:"volumes,omitempty" json:"volumes,omitempty"`

	Aliases []CandyAlias `yaml:"aliases,omitempty" json:"aliases,omitempty"`

	// --- security / hooks (the OCI-label-collector surface: CollectSecurity/CollectHooks
	// read this per-candy field then apply the box-level #ResolvedBoxView.security override) ---
	Security *Security `yaml:"security,omitempty" json:"security,omitempty"`

	Hook *CandyHook `yaml:"hook,omitempty" json:"hook,omitempty"`

	// --- validate read-surface (candy-local config the validate ENGINE checks) ---
	// external_builder: the reserved word of an EXTERNAL builder plugin this candy selects
	// (from the candy manifest external_builder:). validateCandyContents reads it to accept a
	// candy whose only content is an external-builder selection (deploykit EmitExternalBuilderStages).
	ExternalBuilder string `yaml:"external_builder,omitempty" json:"external_builder,omitempty"`

	// (the candy-level `libvirt:` field was removed here alongside #Candy — see
	// candy.cue's note; CollectLibvirtSnippets, its only reader, was already dead.)
	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`

	PortRelayPorts []int `yaml:"port_relay,omitempty" json:"port_relay,omitempty"`

	ServiceFiles []string `yaml:"service_files,omitempty" json:"service_files,omitempty"`

	EnvRequire []EnvDependency `yaml:"env_require,omitempty" json:"env_require,omitempty"`

	EnvAccept []EnvDependency `yaml:"env_accept,omitempty" json:"env_accept,omitempty"`

	SecretRequire []EnvDependency `yaml:"secret_require,omitempty" json:"secret_require,omitempty"`

	SecretAccept []EnvDependency `yaml:"secret_accept,omitempty" json:"secret_accept,omitempty"`

	MCPRequire []EnvDependency `yaml:"mcp_require,omitempty" json:"mcp_require,omitempty"`

	MCPAccept []EnvDependency `yaml:"mcp_accept,omitempty" json:"mcp_accept,omitempty"`

	// --- W9 mass-edit interface-completeness fill: the remaining fields the 42-file
	// CandyReader repoint needs, already authored on #Candy (candy.cue) but not yet
	// projected onto the build model. artifact/requires_capability/secret/port mirror
	// candy.cue's own fields+shapes exactly; capability widens the CandyView's narrow
	// (preserve_user-only) #CandyCapabilitiesView to the full authored #CandyCapability.
	Artifact []CandyArtifact `yaml:"artifact,omitempty" json:"artifact,omitempty"`

	RequiresCapability []string `yaml:"requires_capability,omitempty" json:"requires_capability,omitempty"`

	Capability *CandyCapability `yaml:"capability,omitempty" json:"capability,omitempty"`

	Secret []CandySecret `yaml:"secret,omitempty" json:"secret,omitempty"`

	// port mirrors candy.cue's own union shape exactly (a plain int OR a "proto:port" string,
	// normalized Go-side to PortSpec — there is no reusable #PortSpec def, per candy.cue's own note).
	Port []PortSpec `yaml:"port,omitempty" json:"port,omitempty"`

	// bake_plugin: the FINAL bare-string form (post remote-sibling qualification — see
	// spec.CandyRefs, the hand-written pipeline-state type carrying the rich pre-qualification
	// form). generate.go's emitBakedPlugins reads this to COPY the plugin's pre-built provider
	// binary into every composing image.
	BakePlugin []CandyRef `yaml:"bake_plugin,omitempty" json:"bake_plugin,omitempty"`
}

type CandyReader interface {
	GetName() string
	GetSourceDir() string
	GetVersion() string
	Vars() map[string]string
	PlanSteps() []Step
	Reboot() bool
	Apk() []ApkPackageSpec
	EnvConfig() (*EnvConfig, error)
	Service() []CandyService
	Shell() *Shell
	TopPackages() []string
	FormatSection(name string) *PackageSection
	LocalPkg(format string) string
	TagSection(tag string) *TagPkgConfig
	HasFile(filename string) bool

	// P8 render-delta accessors (build-mode graph/render surface). Field-backed
	// members use Get* to avoid a field/method name collision on the charly *Candy
	// implementer; the three already-methods keep their names.
	GetIncludedCandy() []CandyRefEntry // candy: composition refs (splicing)
	GetRequire() []CandyRefEntry       // require: deps (ordering + resolution)
	// GetBakePlugin (W9): bake_plugin: out-of-tree plugin candies baked into composing images
	// (generate.go emitBakedPlugins). Same bare-string-wrapped-as-CandyRefEntry shape as
	// GetRequire/GetIncludedCandy above (CandyModel.BakePlugin is the FINAL bare-string wire
	// form; the adapter re-wraps it so callers keep using .Bare() uniformly).
	GetBakePlugin() []CandyRefEntry
	HasContent() bool
	HasInstallFiles() bool // at least one install file (drives pixi-bound detection)
	PixiManifest() string
	GetHasPackageJson() bool
	GetHasCargoToml() bool
	GetExternalBuilder() string // external_builder: word (the out-of-tree builder plugin this candy selects)
	HasFormatPackages() bool
	GetRemote() bool // true if the candy came from a remote repo
	HasExtract() bool
	Extract() []CandyExtract
	HasData() bool
	Data() []CandyData
	GetHasPixiLock() bool
	GetRepoPath() string
	GetSubPathPrefix() string
	HasEnv() bool
	HasRoute() bool
	Route() (*RouteConfig, error)

	// P8 init-cluster accessors (emitInitAssembly/emitInitFragmentStages/
	// generateInitFragments). RelayPorts wraps the field-backed PortRelayPorts to
	// avoid a field/method name collision on the charly *Candy implementer.
	HasInit(initName string) bool // this candy contributes to the named init system
	ServiceFiles() []string       // file_copy-model service unit paths (globbed)
	RelayPorts() []int            // port_relay: ports (init-agnostic)

	// P8 writeCandySteps accessors.
	HasTasks() bool // the candy has any tasks: (runOps non-empty)
	RunOps() []Op   // the candy's plan lowered to build-mode run ops

	// OCI-label-collector surface (CollectSecurity/CollectHooks/layer_secrets):
	// per-candy security/hooks + the six env/secret/mcp dependency lists.
	Security() *Security
	Hooks() *CandyHook
	EnvRequire() []EnvDependency
	EnvAccept() []EnvDependency
	SecretRequire() []EnvDependency
	SecretAccept() []EnvDependency
	MCPRequire() []EnvDependency
	MCPAccept() []EnvDependency

	// W9 mass-edit interface-completeness fill: the remaining accessors the 42-file
	// repoint needs (CollectBoxAlias/CollectBoxVolume/ports.go/layer_capabilities.go/…)
	// — every one of these already exists on the charly *Candy implementer (layers.go);
	// this is a pure exposure widening, no new *Candy behavior. (Libvirt()/HasLibvirt()
	// were added here for this same fill, to serve charly/libvirt.go's
	// CollectLibvirtSnippets — that caller was dead code [box-level `libvirt:` was
	// removed in the VM hard-cutover] and was deleted, and the candy-level `libvirt:`
	// field itself was removed from the schema in the SAME cutover [candy.cue /
	// candymodel.cue, migrated by candy/plugin-migrate's stripCandyLibvirtField] — so
	// these two accessors are gone too, not merely deprecated.)
	// Consumer-set audited: HasAnyInit/HasAnyPackages/HasApk/HasService/HasTagPackages
	// were considered and DROPPED — zero external caller outside layers.go itself (they
	// back OTHER *Candy-internal composition, e.g. HasContent/HasInstallFiles, which
	// stays a host-precomputed field per the #67 predicate-carrying pattern above).
	Alias() []CandyAlias
	HasAliases() bool
	Volume() []CandyVolume
	HasVolumes() bool
	Artifact() []CandyArtifact
	Capabilities() *CandyCapability
	RequiresCapabilities() []string
	Engine() string
	EnvProvides() map[string]string
	MCPProvide() []CandyMCPProvide
	Secret() []CandySecret
	Port() ([]string, error)
	PortSpecs() []PortSpec
	LocalPkgFormats() []string
	HasEnvAccepts() bool
	HasEnvProvides() bool
	HasEnvRequires() bool
	HasMCPAccepts() bool
	HasMCPProvides() bool
	HasMCPRequires() bool
	HasPorts() bool
	HasSecretAccepts() bool
	HasSecretRequires() bool

	// W9 pipeline-retype fill: the candy's OWN `plugin:` declaration (registerExternalVerbsFromCandies'
	// data-read half, findCommandPluginCandy) — the provider REGISTRATION itself stays core-M
	// (touches the providerRegistry), but recognizing which capability words a scanned candy
	// declares is a plain data read the interface must expose once *Candy is gone.
	IsPluginCandy() bool
	GetPluginSource() string
	GetPluginProviders() []string

	// W9 pipeline-retype fill: identity-view scalars multiple OCI-label-collector consumers
	// (render_baked_metadata.go's candyStatus/worst-of-status + info-parts walk) need directly —
	// widely-needed enough to earn a real interface method, unlike the FULL identity view
	// (Description/Info/IsPlugin's sibling fields + the FormatSections/TagSections/RunOps maps)
	// resolved_project_host.go alone needs via the RawCandy() escape hatch.
	GetStatus() string
	GetDescription() string

	// W9 federated-control-plane fill: the candy-declared `agent_provide:`/`terminal_profile:`
	// surfaces (56b1a6b) the OCI-label-collector (render_baked_metadata.go's per-box
	// agent/terminal aggregation) needs once *Candy is gone.
	AgentProvide() []AgentRuntimeCapability
	HasAgentProvides() bool
	TerminalProfiles() map[string]TerminalProfile
}

type CandyRef = string

type CandyRefEntry struct {
	Raw string // original ref, e.g. "@github.com/org/repo/candy/x:v1" or bare "x"
	// Resolved is the qualified candy-map key assigned when a freshly-fetched
	// remote candy's plain-name sibling deps are qualified to
	// "<repo>/<subpathprefix><name>" (qualifyRemoteSiblingDeps). Empty for every
	// other ref, where the map key derives from Raw.
	Resolved string
}

type CandyRefs struct {
	Require       []CandyRefEntry
	IncludedCandy []CandyRefEntry
	BakePlugin    []CandyRefEntry
}

type CandyRoute struct {
	Host string `yaml:"host,omitempty" json:"host"`

	Port int `yaml:"port,omitempty" json:"port"`
}

type CandyScanner interface {
	ScanCandyManifest(path, name, manifestName string, parseManifest func(path string) (*Candy, error)) (CandyModel, CandyView, CandyRefs, error)
	// ScanInlineCandy builds the two views for a candy declared INLINE in a unified charly.yml —
	// ly is already the parsed body (no manifest file, no parseManifest seam needed). sourceDir is
	// the charly.yml's own directory.
	ScanInlineCandy(name, sourceDir string, ly *Candy) (CandyModel, CandyView, CandyRefs)
	// ScanRemoteCandy scans specific candies out of a downloaded remote repository directory —
	// only the bare refs in wantRefs (each "github.com/org/repo/candy/x" form). Sets each result's
	// CandyView.Remote/.RepoPath/.SubPathPrefix and runs the remote-sibling-dep qualification
	// (QualifyRemoteSiblingDeps) before returning, mirroring the pre-move charly/layers.go
	// ScanRemoteCandy, which did the same two things (post-scan.Remote/RepoPath/SubPathPrefix
	// mutation, then qualifyRemoteSiblingDeps) on the live *Candy it had just built.
	ScanRemoteCandy(repoDir, repoPath string, wantRefs map[string]bool, parseManifest func(path string) (*Candy, error)) (map[string]ScannedCandy, error)
}

type CandySecret struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Target string `yaml:"target,omitempty" json:"target,omitempty"`

	Env string `yaml:"env,omitempty" json:"env,omitempty"`
}

type CandyService struct {
	Name string `yaml:"name,omitempty" json:"name"`

	UsePackaged string `yaml:"use_packaged,omitempty" json:"use_packaged,omitempty"`

	Exec string `yaml:"exec,omitempty" json:"exec,omitempty"`

	// distro restricts this entry to the named distros — a bare distro name
	// ("debian") or a versioned tag ("debian:13"). Empty = every distro (the
	// backward-compatible default). The service analogue of a check step's
	// exclude_distros: — it lets ONE candy carry per-distro-DIVERGENT packaged
	// units / exec daemons (the modular virtqemud.socket + virtnetworkd.socket
	// on Fedora/Arch vs the monolithic libvirtd.socket on Debian/Ubuntu, whose
	// libvirt is built without the split daemons) WITHOUT a <name>-host sibling
	// candy (CLAUDE.md "Init-system polymorphism"; R3). Filtered at render time
	// against the target distro tag chain (compileServiceSteps + generate.go).
	Distro []string `yaml:"distro,omitempty" json:"distro,omitempty"`

	Env StrMap `yaml:"env,omitempty" json:"env,omitempty"`

	Restart string `yaml:"restart,omitempty" json:"restart,omitempty"`

	WorkingDirectory string `yaml:"working_directory,omitempty" json:"working_directory,omitempty"`

	User string `yaml:"user,omitempty" json:"user,omitempty"`

	After []string `yaml:"after,omitempty" json:"after,omitempty"`

	Before []string `yaml:"before,omitempty" json:"before,omitempty"`

	WantedBy []string `yaml:"wanted_by,omitempty" json:"wanted_by,omitempty"`

	Stdout string `yaml:"stdout,omitempty" json:"stdout,omitempty"`

	StopTimeout string `yaml:"stop_timeout,omitempty" json:"stop_timeout,omitempty"`

	Scope string `yaml:"scope,omitempty" json:"scope,omitempty"`

	Enable bool `yaml:"enable,omitempty" json:"enable,omitempty"`

	Overrides *CandyServiceOverrides `yaml:"overrides,omitempty" json:"overrides,omitempty"`

	Kind string `yaml:"kind,omitempty" json:"kind,omitempty"`

	Events string `yaml:"event,omitempty" json:"event,omitempty"`

	AutoStart *bool `yaml:"auto_start,omitempty" json:"auto_start,omitempty"`

	StartRetries int `yaml:"start_retry,omitempty" json:"start_retry,omitempty"`

	StartSecs int `yaml:"start_sec,omitempty" json:"start_sec,omitempty"`

	StopSignal string `yaml:"stop_signal,omitempty" json:"stop_signal,omitempty"`

	ExitCode string `yaml:"exit_code,omitempty" json:"exit_code,omitempty"`

	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`
}

type CandyServiceOverrides struct {
	Env StrMap `yaml:"env,omitempty" json:"env,omitempty"`

	After []string `yaml:"after,omitempty" json:"after,omitempty"`

	Exec string `yaml:"exec,omitempty" json:"exec,omitempty"`
}

type CandyView struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Version string `yaml:"version,omitempty" json:"version,omitempty"`

	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	Status string `yaml:"status,omitempty" json:"status,omitempty"`

	Info string `yaml:"info,omitempty" json:"info,omitempty"`

	Remote bool `yaml:"remote,omitempty" json:"remote,omitempty"`

	RepoPath string `yaml:"repo_path,omitempty" json:"repo_path,omitempty"`

	// sub_path_prefix — the parent directory within the repo for sibling ref resolution
	// (e.g. "candy/"). Build-mode remote-candy COPY-source leg: RepoPath + SubPathPrefix +
	// ref reconstruct a remote candy's context path. Filled by the resolve projector; the
	// specCandyAdapter returns it so the plugin-side render reproduces remote COPY sources
	// WITHOUT the live *Candy (K3-D render move, #67 — the GetSubPathPrefix deferral).
	SubPathPrefix string `yaml:"sub_path_prefix,omitempty" json:"sub_path_prefix,omitempty"`

	IsPlugin bool `yaml:"is_plugin,omitempty" json:"is_plugin,omitempty"`

	// the candy's OWN declared plugin block (validatePluginCandy SUBJECT, task #60): the
	// `plugin.providers:` capability strings + `plugin.source:` so the validate plugin can check each
	// declared BUILTIN `<class>:<word>` is a member of ResolvedProject.ProviderCapabilities (the TARGET
	// set). Empty for a non-plugin candy. is_plugin stays the cheap presence bool for inspect/list.
	PluginProviders []string `yaml:"plugin_providers,omitempty" json:"plugin_providers,omitempty"`

	PluginSource string `yaml:"plugin_source,omitempty" json:"plugin_source,omitempty"`

	Require []CandyRef `yaml:"require,omitempty" json:"require,omitempty"`

	IncludedCandy []CandyRef `yaml:"candy,omitempty" json:"candy,omitempty"`

	EnvProvides map[string]string `yaml:"env_provide,omitempty" json:"env_provide,omitempty"`

	MCPProvide []CandyMCPProvide `yaml:"mcp_provide,omitempty" json:"mcp_provide,omitempty"`

	AgentProvide []AgentRuntimeCapability `yaml:"agent_provide,omitempty" json:"agent_provide,omitempty"`

	TerminalProfiles map[string]TerminalProfile `yaml:"terminal_profiles,omitempty" json:"terminal_profiles,omitempty"`

	Ports []int64 `yaml:"port,omitempty" json:"port,omitempty"`

	ServiceNames []string `yaml:"service_name,omitempty" json:"service_name,omitempty"`

	// per-candy list-subcommand sources: `charly box list routes|volumes|aliases|services`.
	// route/volumes/aliases carry the authored detail each subcommand prints (their presence IS
	// the RouteCandy/VolumeCandy/AliasCandy predicate). has_init + port_relay reconstruct the
	// InitCandy predicate (HasAnyInit() || PortRelayPorts>0) for `list services`.
	Route *RouteConfig `yaml:"route,omitempty" json:"route,omitempty"`

	Volumes []CandyVolume `yaml:"volumes,omitempty" json:"volumes,omitempty"`

	Aliases []CandyAlias `yaml:"aliases,omitempty" json:"aliases,omitempty"`

	HasInit bool `yaml:"has_init,omitempty" json:"has_init,omitempty"`

	// init_systems — the PER-INIT-SYSTEM trigger map (W9 finding: HasInit alone is one AGGREGATE
	// "any init" bool, which cannot answer "does this candy trigger init system Y" — the question
	// deploykit's HasInit(initName) / sdk/deploykit's EmitInitFragmentStages actually ask). Mirrors
	// the live *Candy.InitSystems field exactly; populated by the SAME cross-candy host-completion
	// pass PopulateCandyInitSystem runs (once, after every candy is scanned) — see
	// sdk/deploykit.specCandyAdapter.HasInit, which reads this field directly.
	InitSystems map[string]bool `yaml:"init_systems,omitempty" json:"init_systems,omitempty"`

	PortRelayPorts []int `yaml:"port_relay,omitempty" json:"port_relay,omitempty"`

	// capabilities — the per-candy capability surface the validate ENGINE reads (task #60,
	// ruling a). The projector fills it from the candy's `capabilities:` block; the validate
	// plugin re-runs AggregateCandyCapabilities over a box's candy order (a boolean OR of
	// preserve_user, order-independent) + the PreserveUser rule (validateInitDependencies +
	// validatePackagedServices box-arms). An aggregate over RESOLVED models belongs on the
	// envelope, not a host route-B diagnostic — a lean envelope is not a virtue when it keeps
	// an R-rule in core.
	Capabilities *CandyCapabilitiesView `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
}

type CandyVolume struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Path string `yaml:"path,omitempty" json:"path"`
}

type CandyYAML = Candy

type CapabilityInitDef struct {
	Entrypoint []string `yaml:"entrypoint,omitempty" json:"entrypoint,omitempty"`

	FallbackEntrypoint []string `yaml:"fallback_entrypoint,omitempty" json:"fallback_entrypoint,omitempty"`

	ManagementTool string `yaml:"management_tool,omitempty" json:"management_tool,omitempty"`

	ManagementCommands map[string]string `yaml:"management_commands,omitempty" json:"management_commands,omitempty"`
}

type CapabilityService struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Scope string `yaml:"scope,omitempty" json:"scope,omitempty"`

	Enable bool `yaml:"enable,omitempty" json:"enable,omitempty"`

	UsePackaged string `yaml:"use_packaged,omitempty" json:"use_packaged,omitempty"`

	Exec string `yaml:"exec,omitempty" json:"exec,omitempty"`

	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`

	Restart string `yaml:"restart,omitempty" json:"restart,omitempty"`

	WorkingDirectory string `yaml:"working_directory,omitempty" json:"working_directory,omitempty"`

	User string `yaml:"user,omitempty" json:"user,omitempty"`

	After []string `yaml:"after,omitempty" json:"after,omitempty"`

	Before []string `yaml:"before,omitempty" json:"before,omitempty"`

	Stdout string `yaml:"stdout,omitempty" json:"stdout,omitempty"`

	StopTimeout string `yaml:"stop_timeout,omitempty" json:"stop_timeout,omitempty"`

	Kind string `yaml:"kind,omitempty" json:"kind,omitempty"`

	Events string `yaml:"events,omitempty" json:"events,omitempty"`

	AutoStart *bool `yaml:"auto_start,omitempty" json:"auto_start,omitempty"`

	StartRetries int `yaml:"start_retries,omitempty" json:"start_retries,omitempty"`

	StartSec int `yaml:"start_sec,omitempty" json:"start_sec,omitempty"`

	StopSignal string `yaml:"stop_signal,omitempty" json:"stop_signal,omitempty"`

	ExitCode string `yaml:"exit_code,omitempty" json:"exit_code,omitempty"`

	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`

	Init string `yaml:"init,omitempty" json:"init,omitempty"`

	Candy string `yaml:"candy,omitempty" json:"candy,omitempty"`
}

type Check Deploy

type CheckBedMember struct {
	Key string `yaml:"key,omitempty" json:"key"`

	IsVM bool `yaml:"is_vm,omitempty" json:"is_vm,omitempty"`

	Image string `yaml:"image,omitempty" json:"image,omitempty"`

	From string `yaml:"from,omitempty" json:"from,omitempty"`
}

type CheckBedPrereqSkip struct {
	Token string `yaml:"token,omitempty" json:"token"`

	Vendor string `yaml:"vendor,omitempty" json:"vendor"`

	Reason string `yaml:"reason,omitempty" json:"reason"`
}

type CheckBedReply struct {
	Calver string `yaml:"calver,omitempty" json:"calver,omitempty"`

	LogDir string `yaml:"log_dir,omitempty" json:"log_dir,omitempty"`

	PrereqSkip *CheckBedPrereqSkip `yaml:"prereq_skip,omitempty" json:"prereq_skip,omitempty"`

	// BedDescriptor — the substrate classification + refs the plugin drives from.
	IsVM bool `yaml:"is_vm,omitempty" json:"is_vm,omitempty"`

	IsLocal bool `yaml:"is_local,omitempty" json:"is_local,omitempty"`

	IsGroup bool `yaml:"is_group,omitempty" json:"is_group,omitempty"`

	IsExternal bool `yaml:"is_external,omitempty" json:"is_external,omitempty"`

	Image string `yaml:"image,omitempty" json:"image,omitempty"`

	HasAddCandy bool `yaml:"has_add_candy,omitempty" json:"has_add_candy,omitempty"`

	// bed) — bed_run.go skips --tag at the config/start steps for such a bed: the FRESH artifact to
	// verify is the overlay deploy-add just built + persisted (resolved via
	// resolveDeployResolvedImage, the overlay-plans ctx-seed fix's companion bug), not the base
	// image's own --tag build ref.
	VMTemplate string `yaml:"vm_template,omitempty" json:"vm_template,omitempty"`

	BedDomain string `yaml:"bed_domain,omitempty" json:"bed_domain,omitempty"`

	ImageTag string `yaml:"image_tag,omitempty" json:"image_tag,omitempty"`

	LocalRef string `yaml:"local_ref,omitempty" json:"local_ref,omitempty"`

	VMDomains []string `yaml:"vm_domains,omitempty" json:"vm_domains,omitempty"`

	CheckLiveRefs []string `yaml:"check_live_refs,omitempty" json:"check_live_refs,omitempty"`

	ChildKeys []string `yaml:"child_keys,omitempty" json:"child_keys,omitempty"`

	// local_child_keys is the HOST-ROOTED (kind:local) subset of child_keys, in the same order. A VM
	// root deploys ONLY these host-side (mirroring the core deployNestedLocalChildren): a VM's
	// nested CONTAINER children are deployed in-guest by plugin-deploy-vm's PostApply, so a host-side
	// re-deploy would be wrong. The pod path uses child_keys (all); the vm path uses local_child_keys.
	LocalChildKeys []string `yaml:"local_child_keys,omitempty" json:"local_child_keys,omitempty"`

	// members carries each sibling member's build coordinates so a GROUP bed's plugin can drive the
	// per-member image build loop (`charly vm build <from>` / `charly box build <image>` + check box)
	// BEFORE the host `members-up` op deploys them (bringUpMembers assumes pre-built images).
	Members []CheckBedMember `yaml:"members,omitempty" json:"members,omitempty"`

	RunBuild bool `yaml:"run_build,omitempty" json:"run_build,omitempty"`

	RunRuntime bool `yaml:"run_runtime,omitempty" json:"run_runtime,omitempty"`

	RunAgent bool `yaml:"run_agent,omitempty" json:"run_agent,omitempty"`
}

type CheckBedRequest struct {
	Op string `yaml:"op,omitempty" json:"op"`

	Bed string `yaml:"bed,omitempty" json:"bed"`

	OK bool `yaml:"ok,omitempty" json:"ok,omitempty"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`
}

type CheckEnv struct {
	Box string `yaml:"box,omitempty" json:"box,omitempty"`

	Instance string `yaml:"instance,omitempty" json:"instance,omitempty"`

	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`

	ContainerName string `yaml:"container_name,omitempty" json:"container_name,omitempty"`

	Distros []string `yaml:"distros,omitempty" json:"distros,omitempty"`

	Venue string `yaml:"venue,omitempty" json:"venue,omitempty"`

	VenueKind string `yaml:"venue_kind,omitempty" json:"venue_kind,omitempty"`

	DialTimeoutNs int64 `yaml:"dial_timeout_ns,omitempty" json:"dial_timeout_ns,omitempty"`
}

type CheckLoadPluginsReply struct {
}

type CheckLoadPluginsRequest struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`
}

type CheckResult struct {
	Op *Op `yaml:"op,omitempty" json:"op"`

	Verb string `yaml:"verb,omitempty" json:"verb"`

	Status Status `yaml:"status,omitempty" json:"status"`

	Message string `yaml:"message,omitempty" json:"message"`

	Elapsed time.Duration `yaml:"elapsed,omitempty" json:"elapsed"`

	Attempts int `yaml:"attempts,omitempty" json:"attempts,omitempty"`

	TotalElapsed time.Duration `yaml:"total_elapsed,omitempty" json:"total_elapsed,omitempty"`

	CapturedValue string `yaml:"captured_value,omitempty" json:"captured_value,omitempty"`
}

type CheckRunRequest struct {
	Mode string `yaml:"mode,omitempty" json:"mode"`

	Name string `yaml:"name,omitempty" json:"name,omitempty"`

	Image string `yaml:"image,omitempty" json:"image,omitempty"`

	Instance string `yaml:"instance,omitempty" json:"instance,omitempty"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`

	Section string `yaml:"section,omitempty" json:"section,omitempty"`

	Filter []string `yaml:"filter,omitempty" json:"filter,omitempty"`

	Tag string `yaml:"tag,omitempty" json:"tag,omitempty"`

	Strict bool `yaml:"strict,omitempty" json:"strict,omitempty"`

	Agent string `yaml:"agent,omitempty" json:"agent,omitempty"`

	Timeout string `yaml:"timeout,omitempty" json:"timeout,omitempty"`

	NoAgent bool `yaml:"no_agent,omitempty" json:"no_agent,omitempty"`

	Plan []Step `yaml:"plan,omitempty" json:"plan,omitempty"`
}

type CheckRunResults struct {
	Box string `yaml:"box,omitempty" json:"box,omitempty"`

	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`

	Step []StepScore `yaml:"step,omitempty" json:"step,omitempty"`

	Summary ScoreSummary `yaml:"summary,omitempty" json:"summary"`
}

type CheckVenueResolveReply struct {
	Descriptor VenueDescriptor `yaml:"descriptor,omitempty" json:"descriptor"`

	Kind string `yaml:"kind,omitempty" json:"kind"`

	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`

	Name string `yaml:"name,omitempty" json:"name,omitempty"`

	VMName string `yaml:"vm_name,omitempty" json:"vm_name,omitempty"`

	Nested bool `yaml:"nested,omitempty" json:"nested,omitempty"`
}

type CheckVenueResolveRequest struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Instance string `yaml:"instance,omitempty" json:"instance,omitempty"`
}

type CliReply struct {
	Stdout string `yaml:"stdout,omitempty" json:"stdout,omitempty"`

	ExitCode int `yaml:"exit_code,omitempty" json:"exit_code,omitempty"`

	Error string `yaml:"error,omitempty" json:"error,omitempty"`
}

type CliRequest struct {
	Argv []string `yaml:"argv,omitempty" json:"argv"`

	Capture bool `yaml:"capture,omitempty" json:"capture,omitempty"`

	Combined bool `yaml:"combined,omitempty" json:"combined,omitempty"`

	BestEffort bool `yaml:"best_effort,omitempty" json:"best_effort,omitempty"`
}

type CollectedAlias struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Command string `yaml:"command,omitempty" json:"command"`
}

type Config struct {
	Defaults BoxConfig `yaml:"defaults" json:"defaults"`
	Box      BoxMap    `yaml:"box" json:"box"`
	// Local carries kind:local templates so remote-ref collection + validation walk their candy:
	// lists symmetrically with box candy lists (kind:local templates compose remote @-ref
	// candies too). Populated from UnifiedFile.Local by ProjectConfig() (charly/unified.go).
	Local map[string]json.RawMessage `yaml:"local,omitempty" json:"local,omitempty"`
	// Sidecar carries the project's sidecar-template library as OPAQUE bodies (the raw
	// PluginKinds["sidecar"] map). The kernel never reads their fields — candy/plugin-sidecar's
	// OpResolve owns all sidecar business logic.
	Sidecar map[string]json.RawMessage `yaml:"sidecar,omitempty" json:"sidecar,omitempty"`
	// Namespaces carries child namespaces mounted by namespaced `import:` entries (alias →
	// projected sub-Config). Qualified refs like `cachyos.cachyos` resolve through here.
	// Populated from UnifiedFile.Namespaces by ProjectConfig().
	Namespaces map[string]*Config `yaml:"-"`
}

type ConfigPersistReply struct {
}

type ConfigPersistRequest struct {
	Key string `yaml:"key,omitempty" json:"key"`

	Entity string `yaml:"entity,omitempty" json:"entity,omitempty"`

	VmState *VmDeployState `yaml:"vm_state,omitempty" json:"vm_state,omitempty"`

	Remove bool `yaml:"remove,omitempty" json:"remove,omitempty"`
}

type ConfigResolveReply struct {
	VmJSON RawBody `yaml:"vm_json,omitempty" json:"vm_json,omitempty"`

	ResourcesJSON RawBody `yaml:"resources_json,omitempty" json:"resources_json,omitempty"`

	Claimant string `yaml:"claimant,omitempty" json:"claimant,omitempty"`

	ClaimantNode *Deploy `yaml:"claimant_node,omitempty" json:"claimant_node,omitempty"`

	VmBackend string `yaml:"vm_backend,omitempty" json:"vm_backend,omitempty"`

	BuildEngine string `yaml:"build_engine,omitempty" json:"build_engine,omitempty"`

	RunEngine string `yaml:"run_engine,omitempty" json:"run_engine,omitempty"`

	VmState *VmDeployState `yaml:"vm_state,omitempty" json:"vm_state,omitempty"`

	VmEntities []string `yaml:"vm_entities,omitempty" json:"vm_entities,omitempty"`
}

type ConfigResolveRequest struct {
	Entity string `yaml:"entity,omitempty" json:"entity"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`
}

type ConstructStepReply struct {
	Step *InstallStepView `yaml:"step,omitempty" json:"step,omitempty"`
}

type ConstructStepRequest struct {
	Op Op `yaml:"op,omitempty" json:"op"`

	CandyName string `yaml:"candy_name,omitempty" json:"candy_name"`

	CandySourceDir string `yaml:"candy_source_dir,omitempty" json:"candy_source_dir,omitempty"`

	CandyVars map[string]string `yaml:"candy_vars,omitempty" json:"candy_vars,omitempty"`

	ResolvedUser string `yaml:"resolved_user,omitempty" json:"resolved_user,omitempty"`

	PkgFormat string `yaml:"pkg_format,omitempty" json:"pkg_format,omitempty"`

	DistroTags []string `yaml:"distro_tags,omitempty" json:"distro_tags,omitempty"`
}

type Context = string

type Copy struct {
	Src string `yaml:"src,omitempty" json:"src"`

	Dst string `yaml:"dst,omitempty" json:"dst"`

	Chown bool `yaml:"chown,omitempty" json:"chown,omitempty"`
}

type CredentialHealth struct {
	BackendName string `yaml:"backend_name,omitempty" json:"backend_name"`

	ConfiguredBackend string `yaml:"configured_backend,omitempty" json:"configured_backend"`

	KeyringAvailable bool `yaml:"keyring_available,omitempty" json:"keyring_available"`

	KeyringLocked bool `yaml:"keyring_locked,omitempty" json:"keyring_locked"`

	PlaintextCount int `yaml:"plaintext_count,omitempty" json:"plaintext_count"`

	NoSession bool `yaml:"no_session,omitempty" json:"no_session"`

	CollErr string `yaml:"coll_err,omitempty" json:"coll_err,omitempty"`

	HealthyColls []string `yaml:"healthy_colls,omitempty" json:"healthy_colls,omitempty"`

	BrokenColls []string `yaml:"broken_colls,omitempty" json:"broken_colls,omitempty"`

	IndexTotal int `yaml:"index_total,omitempty" json:"index_total"`

	IndexMissing []string `yaml:"index_missing,omitempty" json:"index_missing,omitempty"`
}

type CredentialMount struct {
	Src string `yaml:"src,omitempty" json:"src"`

	Dst string `yaml:"dst,omitempty" json:"dst"`

	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`

	Optional bool `yaml:"optional,omitempty" json:"optional,omitempty"`
}

type DataYAML = CandyData

type Debootstrap struct {
	Suite string `yaml:"suite,omitempty" json:"suite,omitempty"`

	Mirror string `yaml:"mirror,omitempty" json:"mirror,omitempty"`

	Variant string `yaml:"variant,omitempty" json:"variant,omitempty"`

	Components string `yaml:"components,omitempty" json:"components,omitempty"`

	IncludePackages []string `yaml:"include_package,omitempty" json:"include_package,omitempty"`

	BasePackages []string `yaml:"base_package,omitempty" json:"base_package,omitempty"`

	ExtraRepos []DebootstrapRepo `yaml:"extra_repo,omitempty" json:"extra_repo,omitempty"`
}

type DebootstrapRepo struct {
	Name string `yaml:"name,omitempty" json:"name"`

	URL string `yaml:"url,omitempty" json:"url"`

	Suite string `yaml:"suite,omitempty" json:"suite,omitempty"`

	Components string `yaml:"components,omitempty" json:"components,omitempty"`
}

type Deploy struct {
	Version CalVer `yaml:"version,omitempty" json:"version,omitempty"`

	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	// target is DERIVED from the node's discriminator kind + cross-ref at load
	// (buildBundleNode/inferBundleTarget) — NOT authored in node-form. Optional
	// here so #Check's arms can pin it; the #BundleValue arm (node.cue) rejects an
	// authored `target:` outright. The former default `*"pod"` is dropped (Go's
	// classifyTarget supplies the empty→pod default). Generated as a plain Go
	// `string` (the loader stamps it; the CUE enum still validates a pinned value).
	Target string `yaml:"target,omitempty" json:"target,omitempty"`

	// member_of + inside are loader-DERIVED runtime fields (never authored;
	// rejected by #BundleValue): member_of marks a folded sibling-member entry,
	// inside names the venue a nested resource deploys into. Generated for the Go
	// tree-walker, forbidden in authoring.
	MemberOf string `yaml:"member_of,omitempty" json:"member_of,omitempty"`

	Inside string `yaml:"inside,omitempty" json:"inside,omitempty"`

	// agent_provisioned marks a resource member/child the AI deploys at run time
	// (the iterate-benchmark contract): image-less (no box:), not folded to a
	// top-level entry, exempt from the box-required validators. See deploy.go.
	AgentProvisioned bool `yaml:"agent_provisioned,omitempty" json:"agent_provisioned,omitempty"`

	// descent is the loader-DERIVED venue-hop descriptor (the descent de-type,
	// Cutover H): the substrate plugin stamps it at OpLoad (via kit.StampDescent) so
	// the deploy chain (AppendHopForFlatPath) descends generically BY TRANSPORT,
	// never by switching on the substrate kind word. charly-written state, never
	// authored (rejected by #BundleValue).
	Descent *DescentDescriptor `yaml:"descent,omitempty" json:"descent,omitempty"`

	// EDGE-INHERIT cutover B: the substrate kind is the EDGE discriminator (pod:/vm:/
	// k8s:/local:/android:/group:), so the deploy carries only NON-kind cross-refs:
	//
	//	from  — inherit a SAME-kind template by name (vm/k8s/local/android deploys).
	//	image — the box/OCI artifact a pod/k8s/android RUNS (the former `box:`).
	//
	// Per-substrate validity (image⊻from, source⊻from) is enforced in Go
	// (classifyTarget / validateDeploy), not CUE, so a `vm:` node is a VmSpec template
	// (source:) OR a deploy (from:) under ONE arm — the disjunction #Vm|#Deploy.
	From EntityRef `yaml:"from,omitempty" json:"from,omitempty"`

	Image string `yaml:"image,omitempty" json:"image,omitempty"`

	Kind string `yaml:"kind,omitempty" json:"kind,omitempty"`

	Replica int `yaml:"replica,omitempty" json:"replica,omitempty"`

	Restart string `yaml:"restart,omitempty" json:"restart,omitempty"`

	Schedule string `yaml:"schedule,omitempty" json:"schedule,omitempty"`

	Tunnel *TunnelYAML `yaml:"tunnel,omitempty" json:"tunnel,omitempty"`

	DNS string `yaml:"dns,omitempty" json:"dns,omitempty"`

	AcmeEmail string `yaml:"acme_email,omitempty" json:"acme_email,omitempty"`

	Port []PortPin `yaml:"port,omitempty" json:"port,omitempty"`

	ResolvedPort []PortPin `yaml:"resolved_port,omitempty" json:"resolved_port,omitempty"`

	// resolved_image: the concrete image ref the pod deploy's add_candy: overlay
	// build produced (`<deploy-key>-overlay:<hash>`), persisted by PrepareVenue so
	// config/start deploy EXACTLY that overlay (carrying the add_candy layers)
	// instead of re-resolving the base image: short-name by a CalVer sort that the
	// overlay alias can lose to the base on a same-minute build. charly-written
	// state (like resolved_port), never authored; empty for a plain pod.
	ResolvedImage string `yaml:"resolved_image,omitempty" json:"resolved_image,omitempty"`

	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`

	EnvFile string `yaml:"env_file,omitempty" json:"env_file,omitempty"`

	Network string `yaml:"network,omitempty" json:"network,omitempty"`

	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`

	Security *Security `yaml:"security,omitempty" json:"security,omitempty"`

	Secret []DeploySecret `yaml:"secret,omitempty" json:"secret,omitempty"`

	Volume []DeployVolume `yaml:"volume,omitempty" json:"volume,omitempty"`

	// volume_project_checked marks that this deploy's PROJECT-declared `volume:` override has
	// already been consulted ONCE (true regardless of whether the project declared one), so
	// resolveDeployVolumes (candy/plugin-deploy-pod) never re-queries the project on a
	// subsequent `charly config`/`charly update` merely because the per-host overlay's Volume
	// field happens to be empty (that emptiness is ALSO produced by an unrelated overlay write —
	// e.g. the port-resolution block — that never touched volumes at all, so key-existence alone
	// cannot distinguish "checked, found nothing" from "not checked yet"). charly-written state
	// (like resolved_port/resolved_image), never authored.
	VolumeProjectChecked bool `yaml:"volume_project_checked,omitempty" json:"volume_project_checked,omitempty"`

	// The Go type is OPAQUE (map[string]json.RawMessage): CUE still validates each
	// per-deploy sidecar override against #Sidecar, but the kernel stores it as
	// opaque bodies — ALL sidecar business logic lives in candy/plugin-sidecar's
	// OpResolve (the sidecar de-type, Cutover D). The host never reads Sidecar fields.
	Sidecar map[string]RawBody `yaml:"sidecar,omitempty" json:"sidecar,omitempty"`

	ForwardGpgAgent *bool `yaml:"forward_gpg_agent,omitempty" json:"forward_gpg_agent,omitempty"`

	ForwardSshAgent *bool `yaml:"forward_ssh_agent,omitempty" json:"forward_ssh_agent,omitempty"`

	Plan []Step `yaml:"plan,omitempty" json:"plan,omitempty"`

	Iterate *Iterate `yaml:"iterate,omitempty" json:"iterate,omitempty"`

	AddCandy []string `yaml:"add_candy,omitempty" json:"add_candy,omitempty"`

	InstallOpts *InstallOpts `yaml:"install_opts,omitempty" json:"install_opts,omitempty"`

	Host string `yaml:"host,omitempty" json:"host,omitempty"`

	User string `yaml:"user,omitempty" json:"user,omitempty"`

	SSHArgs []string `yaml:"ssh_arg,omitempty" json:"ssh_arg,omitempty"`

	Cpus int `yaml:"cpus,omitempty" json:"cpus,omitempty"`

	Ram VmSize `yaml:"ram,omitempty" json:"ram,omitempty"`

	DiskSize VmSize `yaml:"disk_size,omitempty" json:"disk_size,omitempty"`

	Kubernetes *K8sDeploy `yaml:"kubernetes,omitempty" json:"kubernetes,omitempty"`

	Resources *DeployResources `yaml:"resources,omitempty" json:"resources,omitempty"`

	Expose *DeployExpose `yaml:"expose,omitempty" json:"expose,omitempty"`

	Storage []DeployStorage `yaml:"storage,omitempty" json:"storage,omitempty"`

	Probes *DeployProbes `yaml:"probes,omitempty" json:"probes,omitempty"`

	FromSnapshot string `yaml:"from_snapshot,omitempty" json:"from_snapshot,omitempty"`

	CloudInitClean bool `yaml:"cloud_init_clean,omitempty" json:"cloud_init_clean,omitempty"`

	VmState *VmDeployState `yaml:"vm_state,omitempty" json:"vm_state,omitempty"`

	Disposable *bool `yaml:"disposable,omitempty" json:"disposable,omitempty"`

	Lifecycle string `yaml:"lifecycle,omitempty" json:"lifecycle,omitempty"`

	Ephemeral *EphemeralLifetime `yaml:"ephemeral,omitempty" json:"ephemeral,omitempty"`

	Preemptible *PreemptibleConfig `yaml:"preemptible,omitempty" json:"preemptible,omitempty"`

	RequiresExclusive []string `yaml:"requires_exclusive,omitempty" json:"requires_exclusive,omitempty"`

	RequiresShared []string `yaml:"requires_shared,omitempty" json:"requires_shared,omitempty"`

	// nested/peer map keys carry no dots (validateDeploymentName). Loader-built
	// runtime tree maps (Children = nested-inside venue; Members = brought-up
	// alongside on the shared network) — gengotypes can't express a pattern-keyed
	// self-referential map, so the Go type is pinned explicitly.
	Children map[string]*Deploy `yaml:"nested,omitempty" json:"nested,omitempty"`

	Members map[string]*Deploy `yaml:"peer,omitempty" json:"peer,omitempty"`
}

type DeployAddReply struct {
}

type DeployAddRequest struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Ref string `yaml:"ref,omitempty" json:"ref,omitempty"`

	AddCandy []string `yaml:"add_candy,omitempty" json:"add_candy,omitempty"`

	Tag string `yaml:"tag,omitempty" json:"tag,omitempty"`

	DryRun bool `yaml:"dry_run,omitempty" json:"dry_run,omitempty"`

	NodeOnly bool `yaml:"node_only,omitempty" json:"node_only,omitempty"`

	Format string `yaml:"format,omitempty" json:"format,omitempty"`

	Pull bool `yaml:"pull,omitempty" json:"pull,omitempty"`

	Verify bool `yaml:"verify,omitempty" json:"verify,omitempty"`

	WithServices bool `yaml:"with_services,omitempty" json:"with_services,omitempty"`

	AllowRepoChanges bool `yaml:"allow_repo_changes,omitempty" json:"allow_repo_changes,omitempty"`

	AllowRootTasks bool `yaml:"allow_root_tasks,omitempty" json:"allow_root_tasks,omitempty"`

	SkipIncompatible bool `yaml:"skip_incompatible,omitempty" json:"skip_incompatible,omitempty"`

	BuilderImage string `yaml:"builder_image,omitempty" json:"builder_image,omitempty"`

	AssumeYes bool `yaml:"assume_yes,omitempty" json:"assume_yes,omitempty"`

	Disposable bool `yaml:"disposable,omitempty" json:"disposable,omitempty"`

	Lifecycle string `yaml:"lifecycle,omitempty" json:"lifecycle,omitempty"`
}

type DeployArtifactsRetrieveReply struct {
}

type DeployArtifactsRetrieveRequest struct {
	Dir string `yaml:"dir,omitempty" json:"dir"`

	PlansJSON RawBody `yaml:"plans_json,omitempty" json:"plans_json"`

	ArtifactKey string `yaml:"artifact_key,omitempty" json:"artifact_key"`

	DeployName string `yaml:"deploy_name,omitempty" json:"deploy_name"`

	ArtifactEnv map[string]string `yaml:"artifact_env,omitempty" json:"artifact_env,omitempty"`

	VenueJSON RawBody `yaml:"venue_json,omitempty" json:"venue_json,omitempty"`
}

type DeployCandySecretsReply struct {
	SecretEnv map[string]string `yaml:"secret_env,omitempty" json:"secret_env,omitempty"`

	RegisterHints []string `yaml:"register_hints,omitempty" json:"register_hints,omitempty"`
}

type DeployCandySecretsRequest struct {
	Dir string `yaml:"dir,omitempty" json:"dir"`

	PlansJSON RawBody `yaml:"plans_json,omitempty" json:"plans_json"`
}

type DeployCompileReply struct {
	PlansJSON RawBody `yaml:"plans,omitempty" json:"plans"`

	Base string `yaml:"base,omitempty" json:"base,omitempty"`

	CandySet []string `yaml:"candy_set,omitempty" json:"candy_set,omitempty"`
}

type DeployCompileRequest struct {
	Dir string `yaml:"dir,omitempty" json:"dir"`

	BoxView ResolvedBoxView `yaml:"box_view,omitempty" json:"box_view,omitempty"`

	Order []string `yaml:"order,omitempty" json:"order,omitempty"`

	HostContextJSON RawBody `yaml:"host_context,omitempty" json:"host_context"`

	Tag string `yaml:"tag,omitempty" json:"tag,omitempty"`

	// The add_candy:/--add-candy ref(s) (if any) this compile call's own candy set was widened
	// with host-side (scanCandiesForRef's synthetic-augmented scan, for a REMOTE ref) — threaded
	// into the plugin's OWN HostBuild("resolved-project") re-fetch (as its extra_candy_refs) so
	// the envelope's candy map ALSO carries them (RCA'd K1-alpha regression: the two scans were
	// independent, so a remote add-candy resolved host-side never reached the envelope).
	ExtraCandyRefs []string `yaml:"extra_candy_refs,omitempty" json:"extra_candy_refs,omitempty"`

	// candy_ref selects the CANDY shape above (K4 unit B): the authored ref string (bare local
	// name OR a `@github…` remote ref) the plugin resolves via BareRef against its own
	// rp.CandyModels/rp.Candies (widened, when remote, by extra_candy_refs carrying the SAME raw
	// ref — mirroring compileStandaloneCandySelection's ExtraCandyRefs: []string{ref.Raw}
	// widening). Absent for the other shapes.
	CandyRef string `yaml:"candy_ref,omitempty" json:"candy_ref,omitempty"`

	// vm_entity selects the CANDY shape's synthetic-box kind, TOLERANTLY (mirrors the OLD host
	// syntheticVmBox call site exactly — never a hard requirement): the plugin tries vm_entity
	// against its own rp.Templates.VM; a HIT resolves it via the kind:vm provider's OpResolve leg
	// for a guest-tuned box; a MISS (including vm_entity=="") falls through to a plain host-adhoc
	// box via vmshared.DetectHostDistro. A non-vm deploy's node.From (e.g. a `local:` node's
	// kind:local template ref) is ALSO threaded into vm_entity upstream (resolveVmEntity returns
	// node.From unconditionally, not only for a real vm cross-ref) — so a miss here is the
	// COMMON case, not an error condition. Ignored for the other shapes.
	VmEntity string `yaml:"vm_entity,omitempty" json:"vm_entity,omitempty"`

	// box_ref selects the BOX-REF shape above (K4 unit B box-half): the box's own name (never a
	// remote ref — compileRefSelection already rejects a remote image ref before this request is
	// built). The plugin's own HostBuild("resolved-project") re-fetch is asked to include_disabled
	// so an explicitly-named `enabled: false` box still resolves (mirrors the OLD host
	// ResolveBox(cfg, ref.Name, …) call, which never checked IsEnabled at all — enabled-filtering
	// is a ResolveAllBox/listing concern, not a by-name-resolve one; zero disabled boxes exist
	// repo-wide today, so this is a zero-cost future-proofing widening, not a live behavior
	// change). Absent for the other shapes.
	BoxRef string `yaml:"box_ref,omitempty" json:"box_ref,omitempty"`

	// base_box_ref selects the ADD-CANDY-ON-BOX shape (K4 box-half completion) WHEN set alongside
	// candy_ref: the primary pod/k8s base image's own name, read from rp.Boxes[base_box_ref] as the
	// COMPILE CONTEXT the candy_ref overlay compiles against — replacing the former host-side
	// buildkit.ResolveBox(baseImg) + scanCandiesForRef. Absent for every other shape (a standalone
	// candy_ref with NO base_box_ref stays the CANDY shape, synthetic-box compiled).
	BaseBoxRef string `yaml:"base_box_ref,omitempty" json:"base_box_ref,omitempty"`
}

type DeployConfigSaveReply struct {
}

type DeployConfigSaveRequest struct {
	ConfigJSON RawBody `yaml:"config,omitempty" json:"config"`
}

type DeployConfigSaveStateReply struct {
}

type DeployConfigSaveStateRequest struct {
	Box string `yaml:"box,omitempty" json:"box"`

	Instance string `yaml:"instance,omitempty" json:"instance,omitempty"`

	InputJSON RawBody `yaml:"input_json,omitempty" json:"input_json"`
}

type DeployDelReply struct {
}

type DeployDelRequest struct {
	Name string `yaml:"name,omitempty" json:"name"`

	AssumeYes bool `yaml:"assume_yes,omitempty" json:"assume_yes,omitempty"`

	KeepRepoChanges bool `yaml:"keep_repo_changes,omitempty" json:"keep_repo_changes,omitempty"`

	KeepServices bool `yaml:"keep_services,omitempty" json:"keep_services,omitempty"`

	KeepImage bool `yaml:"keep_image,omitempty" json:"keep_image,omitempty"`

	DryRun bool `yaml:"dry_run,omitempty" json:"dry_run,omitempty"`
}

type DeployDelResolveReply struct {
	Node *Deploy `yaml:"node,omitempty" json:"node,omitempty"`

	Kind string `yaml:"kind,omitempty" json:"kind,omitempty"`
}

type DeployDelResolveRequest struct {
	Name string `yaml:"name,omitempty" json:"name"`
}

type DeployEntityResolveReply struct {
	Node *Deploy `yaml:"node,omitempty" json:"node,omitempty"`

	EntityJSON RawBody `yaml:"entity,omitempty" json:"entity,omitempty"`
}

type DeployEntityResolveRequest struct {
	Kind string `yaml:"kind,omitempty" json:"kind"`

	Name string `yaml:"name,omitempty" json:"name"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`
}

type DeployExecutor interface {
	// Venue returns a stable identifier for where this executor's
	// commands physically run. Examples:
	//
	//   "local"                            — ShellExecutor.
	//   "ssh://arch@127.0.0.1:2224"        — SSHExecutor.
	//   "nested:podman exec stack/local"   — NestedExecutor over local.
	//   "nested:ssh vm/local"              — NestedExecutor over SSH.
	//
	// The string is used as a map key for per-venue ledgers, so it
	// must be stable across invocations for the same logical target.
	// Not a URL — don't parse it; just compare.
	Venue() string

	// RunSystem executes a bash script with root privileges. On the
	// host, this is `sudo bash -s <<<script`; on the VM target, it's
	// `ssh <user>@<host> sudo bash -s <<<script`. The script body runs
	// with set -e semantics at the caller's discretion.
	RunSystem(ctx context.Context, script string, opts EmitOpts) error

	// RunUser executes a bash script as the invoking user (no sudo).
	// On the host, it's `bash -s <<<script`; on VM, `ssh <user>@<host>
	// bash -s <<<script` where <user> is the unprivileged guest user.
	RunUser(ctx context.Context, script string, opts EmitOpts) error

	// RunBuilder invokes the multi-stage builder image (podman run
	// <builder>) to compile pixi/npm/cargo/aur artifacts. On the host
	// this calls the existing BuilderRun helper. On VM deploys, the
	// builder runs *on the host* and artifacts are scp'd into the
	// guest via PutFile — podman inside the guest is not required.
	RunBuilder(ctx context.Context, opts BuilderRunOpts) ([]byte, error)

	// PutFile places a file at a remote path. ownerRoot == true means
	// the file is chown'd to root:root and chmod'd according to mode.
	// On the host, this is a plain os.WriteFile (plus sudo chown when
	// ownerRoot). On VM, this is scp into a tmp location followed by
	// `sudo install -m <mode> -o root -g root` on the guest.
	PutFile(ctx context.Context, localPath, remotePath string, mode uint32, ownerRoot bool, opts EmitOpts) error

	// GetFile retrieves the contents of a file on the venue. asRoot==true
	// runs the read via sudo to handle paths the deploying user cannot
	// access (e.g. /etc/rancher/k3s/k3s.yaml on a k3s server). On the
	// host, this is os.ReadFile (or `sudo cat` when asRoot). On VM, this
	// is `ssh <host> sudo cat <path>` with stdout captured. On nested
	// executors, delegates through the jump via the parent's own RunSystem
	// semantics. Used by layer_artifacts.go to publish files back to the
	// operator after deploy completion.
	GetFile(ctx context.Context, remotePath string, asRoot bool, opts EmitOpts) ([]byte, error)

	// RunCapture executes a single shell command (or short bash script) on
	// the venue and returns stdout/stderr/exit/err separately. Used by the
	// declarative test runner (testrun.go) to probe target state without
	// the streamed-output ergonomics of RunSystem/RunUser. No root
	// escalation — callers add `sudo` explicitly when needed; mirrors the
	// previous test-time Executor.Exec semantics. After the executor-
	// hierarchy cutover (2026-04), this is the single capture-output
	// method used by every probe across `charly check live`, `charly check box`, and
	// `charly check` scoring.
	RunCapture(ctx context.Context, script string) (stdout, stderr string, exit int, err error)

	// RunInteractive runs a command on the venue wired to the operator's LIVE TTY:
	// stdin/stdout/stderr are INHERITED from the host charly process (the reverse-channel
	// server runs IN that process, so os.Std* IS the operator's terminal). The child
	// (`podman exec -it` / `ssh -t`) owns the PTY, resize (SIGWINCH), and Ctrl-C. Blocks
	// until the session ends; returns its exit code. NOT ctx-deadlined — the TTY owns its
	// lifetime (the hostBuildCli doctrine). Stdio NEVER crosses the plugin wire — only the
	// script + the exit code (F12; the live-stdio sibling of RunCapture). Consumers: `charly
	// shell` (-it) and `charly cmd` (-i, stdin piped). A venue that cannot host an interactive
	// session returns ErrNotSupported.
	RunInteractive(ctx context.Context, script string) (exit int, err error)

	// RunStream runs a command on the venue streaming stdout/stderr LIVE to the operator
	// (inherited os.Stdout/os.Stderr; NO stdin). Blocks until exit. Same host-holds-the-
	// terminal semantics as RunInteractive (F12). Consumer: `charly logs --follow`. Returns
	// ErrNotSupported on a venue that cannot stream.
	RunStream(ctx context.Context, script string) (exit int, err error)

	// Kind returns a coarse classification of the venue used by the test
	// runner for reporting and skip decisions. Values:
	//   "host"      — ShellExecutor (operator's machine)
	//   "container" — NestedExecutor with JumpPodmanExec / JumpDockerExec
	//   "vm"        — SSHExecutor or NestedExecutor with JumpSSH/JumpVirshConsole
	// Replaces the test-time Executor.Kind() method deleted in the
	// 2026-04 executor-hierarchy cutover.
	Kind() string

	// ResolveHome returns the absolute path of $HOME for the named user
	// on the venue. Empty user means "the executor's default user" (the
	// invoking operator for ShellExecutor; the SSH login user for
	// SSHExecutor). Implementations consult `getent passwd` so they
	// don't depend on $HOME being set in the calling environment — that
	// matters for SSH executors where the operator's $HOME has nothing
	// to do with the remote user's home, and for ShellExecutor when the
	// caller wants a different user's home (e.g. running as root but
	// resolving an unprivileged user's home).
	//
	// Bundled as part of the 2026-05 shell:-schema cutover. Replaces the
	// `the local deploy target.HostHome = os.Getenv("HOME")` static-field
	// initialization that mis-targeted SSH deploys: the operator's
	// $HOME is not the remote user's home, so every shell-rc edit
	// (env.d sourcing block included) was landing in the wrong place
	// for `host: user@machine` deploys.
	ResolveHome(ctx context.Context, user string) (string, error)
}

type DeployExpose struct {
	Host string `yaml:"host,omitempty" json:"host,omitempty"`

	Path string `yaml:"path,omitempty" json:"path,omitempty"`

	TLS bool `yaml:"tls,omitempty" json:"tls,omitempty"`

	Port string `yaml:"port,omitempty" json:"port,omitempty"`
}

type DeployFromBoxReply struct {
}

type DeployFromBoxRequest struct {
	Ref string `yaml:"ref,omitempty" json:"ref"`

	Name string `yaml:"name,omitempty" json:"name,omitempty"`

	Instance string `yaml:"instance,omitempty" json:"instance,omitempty"`

	Env []string `yaml:"env,omitempty" json:"env,omitempty"`

	Port []string `yaml:"port,omitempty" json:"port,omitempty"`

	Cluster string `yaml:"cluster,omitempty" json:"cluster,omitempty"`

	Namespace string `yaml:"namespace,omitempty" json:"namespace,omitempty"`
}

type DeployMembersReply struct {
}

type DeployMembersRequest struct {
	Node *Deploy `yaml:"node,omitempty" json:"node,omitempty"`
}

type DeployNodeDelDispatchReply struct {
}

type DeployNodeDelDispatchRequest struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Node *Deploy `yaml:"node,omitempty" json:"node,omitempty"`

	AssumeYes bool `yaml:"assume_yes,omitempty" json:"assume_yes,omitempty"`

	KeepRepoChanges bool `yaml:"keep_repo_changes,omitempty" json:"keep_repo_changes,omitempty"`

	KeepServices bool `yaml:"keep_services,omitempty" json:"keep_services,omitempty"`

	KeepImage bool `yaml:"keep_image,omitempty" json:"keep_image,omitempty"`

	DryRun bool `yaml:"dry_run,omitempty" json:"dry_run,omitempty"`
}

type DeployOverlayReply struct {
	ConfigJSON RawBody `yaml:"config_json,omitempty" json:"config_json,omitempty"`
}

type DeployOverlayRequest struct {
	Context string `yaml:"context,omitempty" json:"context"`
}

type DeployPluginsConnectReply struct {
	Dir string `yaml:"dir,omitempty" json:"dir"`
}

type DeployPluginsConnectRequest struct {
	Path string `yaml:"path,omitempty" json:"path"`

	AddCandy []string `yaml:"add_candy,omitempty" json:"add_candy,omitempty"`
}

type DeployProbes struct {
	Liveness *Op `yaml:"liveness,omitempty" json:"liveness,omitempty"`

	Readiness *Op `yaml:"readiness,omitempty" json:"readiness,omitempty"`

	Startup *Op `yaml:"startup,omitempty" json:"startup,omitempty"`
}

type DeployReply struct {
	ReverseOps []ReverseOp `yaml:"reverse_ops,omitempty" json:"reverse_ops,omitempty"`

	Record DeployReplyRecord `yaml:"record,omitempty" json:"record"`
}

type DeployReplyRecord struct {
	Candy string `yaml:"candy,omitempty" json:"candy"`

	Version string `yaml:"version,omitempty" json:"version,omitempty"`
}

type DeployResolveTargetAddReply struct {
}

type DeployResolveTargetAddRequest struct {
	Path string `yaml:"path,omitempty" json:"path"`

	DeployName string `yaml:"deploy_name,omitempty" json:"deploy_name"`

	Node *Deploy `yaml:"node,omitempty" json:"node,omitempty"`

	Target string `yaml:"target,omitempty" json:"target"`

	Dir string `yaml:"dir,omitempty" json:"dir"`

	// plans_json is the marshalled []spec.InstallPlanView (deployID + AddCandies already stamped
	// plugin-side); the host re-materializes []*spec.InstallPlan via deploykit.PlanFromView.
	PlansJSON RawBody `yaml:"plans_json,omitempty" json:"plans_json"`

	AncestorPaths []string `yaml:"ancestor_paths,omitempty" json:"ancestor_paths,omitempty"`

	AncestorNodes []Deploy `yaml:"ancestor_nodes,omitempty" json:"ancestor_nodes,omitempty"`

	NodeOnly bool `yaml:"node_only,omitempty" json:"node_only,omitempty"`

	Pull bool `yaml:"pull,omitempty" json:"pull,omitempty"`

	Verify bool `yaml:"verify,omitempty" json:"verify,omitempty"`

	WithServices bool `yaml:"with_services,omitempty" json:"with_services,omitempty"`

	AllowRepoChanges bool `yaml:"allow_repo_changes,omitempty" json:"allow_repo_changes,omitempty"`

	AllowRootTasks bool `yaml:"allow_root_tasks,omitempty" json:"allow_root_tasks,omitempty"`

	SkipIncompatible bool `yaml:"skip_incompatible,omitempty" json:"skip_incompatible,omitempty"`

	AssumeYes bool `yaml:"assume_yes,omitempty" json:"assume_yes,omitempty"`

	BuilderImage string `yaml:"builder_image,omitempty" json:"builder_image,omitempty"`
}

type DeployResources struct {
	CPURequest string `yaml:"cpu_request,omitempty" json:"cpu_request,omitempty"`

	MemoryRequest string `yaml:"memory_request,omitempty" json:"memory_request,omitempty"`
}

type DeploySecret struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Source string `yaml:"source,omitempty" json:"source,omitempty"`
}

type DeployStorage struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Size string `yaml:"size,omitempty" json:"size,omitempty"`

	ClassHint string `yaml:"class_hint,omitempty" json:"class_hint,omitempty"`

	Access string `yaml:"access,omitempty" json:"access,omitempty"`

	Path string `yaml:"path,omitempty" json:"path,omitempty"`
}

type DeployTarget interface {
	Name() string
	Emit(plans []*InstallPlan, opts EmitOpts) error
}

type DeployTargetDelOpts struct {
	DryRun bool `yaml:"dry_run,omitempty" json:"dry_run,omitempty"`

	AssumeYes bool `yaml:"assume_yes,omitempty" json:"assume_yes,omitempty"`

	KeepLedger bool `yaml:"keep_ledger,omitempty" json:"keep_ledger,omitempty"`

	RemoveVolumes bool `yaml:"remove_volumes,omitempty" json:"remove_volumes,omitempty"`

	KeepRepoChanges bool `yaml:"keep_repo_changes,omitempty" json:"keep_repo_changes,omitempty"`

	KeepServices bool `yaml:"keep_services,omitempty" json:"keep_services,omitempty"`

	KeepImage bool `yaml:"keep_image,omitempty" json:"keep_image,omitempty"`
}

type DeployTargetDispatchReply struct {
	Status DeployTargetStatus `yaml:"status,omitempty" json:"status,omitempty"`

	Output string `yaml:"output,omitempty" json:"output,omitempty"`

	ExitCode int64 `yaml:"exit_code,omitempty" json:"exit_code,omitempty"`

	VenueJSON RawBody `yaml:"venue_json,omitempty" json:"venue_json,omitempty"`

	ArtifactKey string `yaml:"artifact_key,omitempty" json:"artifact_key,omitempty"`
}

type DeployTargetDispatchRequest struct {
	Op string `yaml:"op,omitempty" json:"op"`

	Name string `yaml:"name,omitempty" json:"name"`

	Word string `yaml:"word,omitempty" json:"word"`

	HasLifecycle bool `yaml:"has_lifecycle,omitempty" json:"has_lifecycle,omitempty"`

	HasPreresolve bool `yaml:"has_preresolve,omitempty" json:"has_preresolve,omitempty"`

	HasPlan bool `yaml:"has_plan,omitempty" json:"has_plan,omitempty"`

	Node *Deploy `yaml:"node,omitempty" json:"node,omitempty"`

	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`

	NodeOnly bool `yaml:"node_only,omitempty" json:"node_only,omitempty"`

	// ledger_root OPTIONALLY overrides the ledger root directory (kit.LedgerPaths.Root) — the
	// pre-S3b externalDeployTarget carried a settable `paths *kit.LedgerPaths` field a TEST could
	// redirect to a temp dir instead of the operator's real ~/.config/opencharly/installed/; this
	// is the wire-safe equivalent (a bare root string, the plugin derives Deploys/Candies/LockFile
	// from it exactly like kit.DefaultLedgerPaths does). Empty (the default) — kit.DefaultLedgerPaths().
	LedgerRoot string `yaml:"ledger_root,omitempty" json:"ledger_root,omitempty"`

	PlansJSON RawBody `yaml:"plans_json,omitempty" json:"plans_json,omitempty"`

	OptsJSON RawBody `yaml:"opts_json,omitempty" json:"opts_json,omitempty"`

	ChecksJSON RawBody `yaml:"checks_json,omitempty" json:"checks_json,omitempty"`

	Cmd []string `yaml:"cmd,omitempty" json:"cmd,omitempty"`

	TTY bool `yaml:"tty,omitempty" json:"tty,omitempty"`

	// venue_json is the ALREADY-MATERIALIZED spec.VenueDescriptor for this deploy. Two distinct
	// producers set it: (a) core, when this dispatch is a NESTED non-lifecycle child (a
	// `local:`/`android:`/`k8s:` deploy under a vm/pod, tree position) — Add flattens the
	// live ancestor executor (EmitOpts.ParentExec) into this field via kit.DescriptorFromExecutor
	// BEFORE the very first "add" dispatch, since that live value cannot itself cross the wire
	// (FIX ROUND, S3b follow-up — its absence on "add" was the R10 bed regression: every nested
	// child silently applied on the operator's host instead of the parent venue); (b) core again,
	// carrying FORWARD a prior dispatch's reported venue for the SAME target's lifetime
	// (Update/Del/Start/Stop/Status/Logs/Shell/Attach/Rebuild, after a lifecycle substrate's "add"
	// already ran PrepareVenue once). Either way the plugin re-materializes it via
	// kit.VenueFromDescriptor instead of re-deriving from the node or re-running PrepareVenue.
	// Absent on "add" for a ROOT (non-nested) OR lifecycle (vm/pod) target — those derive their
	// own venue fresh (root: RootExecutorForDeployNode(node); lifecycle: PrepareVenue).
	VenueJSON RawBody `yaml:"venue_json,omitempty" json:"venue_json,omitempty"`

	// distro_cfg_json is the marshalled *buildkit.DistroConfig ("add"/"update" only) — recordDeploy's
	// FillReverseUninstallCmds needs it to render an aur-builder ReverseOpPackageRemove's
	// UninstallCmd host-side-equivalent, now plugin-side since buildkit.DistroConfig is a plain sdk
	// type with no core-only coupling (unlike the core-only buildEngineContext wrapper it used to
	// travel inside).
	DistroCfgJSON RawBody `yaml:"distro_cfg_json,omitempty" json:"distro_cfg_json,omitempty"`

	// host_env_json is the marshalled spec.HostEnv (CharlyBin/Home/Version) — the R10 bed-found
	// fifth bug in this cluster's move: every lifecycle Op the deleted substrate_lifecycle_grpc.go
	// sent used its OWN hostEnvJSON() helper, computed HOST-side (os.Executable() resolves to the
	// charly binary only when called IN CORE — a plugin's os.Executable() resolves to the PLUGIN
	// binary, wrong for an out-of-process placement even though today's compiled-in placement
	// happened not to crash on it, since a bare `spec.HostEnv{}` zero-value was marshalled instead
	// of ever actually calling it, plugin-side, in the S3b port). Core (unified_targets.go's
	// dispatch, the ONLY place that reliably knows its OWN binary regardless of the substrate's or
	// command:bundle's own placement) now computes it ONCE per dispatch call and threads it here;
	// candy/plugin-bundle forwards it verbatim to every lifecycle Op instead of computing its own.
	HostEnvJSON RawBody `yaml:"host_env_json,omitempty" json:"host_env_json,omitempty"`
}

type DeployTargetLogsOpts struct {
	Follow bool `yaml:"follow,omitempty" json:"follow,omitempty"`

	Tail int64 `yaml:"tail,omitempty" json:"tail,omitempty"`

	Sidecar string `yaml:"sidecar,omitempty" json:"sidecar,omitempty"`
}

type DeployTargetRebuildOpts struct {
	RebuildImage bool `yaml:"rebuild_image,omitempty" json:"rebuild_image,omitempty"`

	AssumeYes bool `yaml:"assume_yes,omitempty" json:"assume_yes,omitempty"`

	DryRun bool `yaml:"dry_run,omitempty" json:"dry_run,omitempty"`
}

type DeployTargetStatus struct {
	State string `yaml:"state,omitempty" json:"state,omitempty"`

	Healthy bool `yaml:"healthy,omitempty" json:"healthy,omitempty"`

	Details map[string]string `yaml:"details,omitempty" json:"details,omitempty"`
}

type DeployTargetTestOpts struct {
	OnlyIDs []string `yaml:"only_ids,omitempty" json:"only_ids,omitempty"`

	FormatJSON bool `yaml:"format_json,omitempty" json:"format_json,omitempty"`

	StopOnFail bool `yaml:"stop_on_fail,omitempty" json:"stop_on_fail,omitempty"`
}

type DeployTraits struct {
	// venue: how commands physically execute in this substrate's venue:
	//
	//	container — podman/docker exec into the container by name (pod).
	//	ssh       — an ssh hop into the guest (vm).
	//	shell     — the substrate's own root executor runs on the host (local; k8s host-side).
	//	parent    — reached via the parent's venue, no own executor (android).
	//	none      — external-in-place (zero value / group).
	Venue string `yaml:"venue,omitempty" json:"venue,omitempty"`

	// image_backed: the substrate runs a baked OCI image (pod).
	ImageBacked bool `yaml:"image_backed,omitempty" json:"image_backed,omitempty"`

	// image_context: the substrate composes over an image build context (pod overlay, k8s manifests).
	ImageContext bool `yaml:"image_context,omitempty" json:"image_context,omitempty"`

	// machine_venue: the substrate is a full machine with a system init (host/vm/local) — its
	// services render as systemd units, not a container init.
	MachineVenue bool `yaml:"machine_venue,omitempty" json:"machine_venue,omitempty"`

	// exclusive_venue: the substrate holds an exclusive host-resource lease boundary (vm).
	ExclusiveVenue bool `yaml:"exclusive_venue,omitempty" json:"exclusive_venue,omitempty"`

	// leaf_only: the substrate is a deploy-chain LEAF — it cannot be descended into (k8s).
	LeafOnly bool `yaml:"leaf_only,omitempty" json:"leaf_only,omitempty"`

	// bracketed_lifecycle: the substrate's Start/Stop accept direct-mode CLI opts (env/port/
	// volume/bind/no-auto-detect on Start, unmount on Stop) AND need the Q1 resource-arbiter
	// claim bracketed around the dispatch (pod). A substrate that manages its own venue
	// lifecycle + resource claim (vm, via `charly vm start`/`stop`) leaves this false.
	BracketedLifecycle bool `yaml:"bracketed_lifecycle,omitempty" json:"bracketed_lifecycle,omitempty"`

	// bed_target: the substrate is a valid `kind:check` bed target — pod/vm/local/android run a
	// disposable check bed; k8s (leaf_only) does not. validateCheckBeds reads this instead of
	// switching on the substrate word (the boundary-law incomplete-seam gate).
	BedTarget bool `yaml:"bed_target,omitempty" json:"bed_target,omitempty"`

	// supports_ephemeral: the substrate's Add/Del path wires the ephemeral register/teardown seam
	// (TTL timer + charly.yml persistence) — vm only today; pod/k8s reject `ephemeral: true` until
	// their Add/Del wire the same seam. validateEphemeral reads this instead of a substrate switch.
	SupportsEphemeral bool `yaml:"supports_ephemeral,omitempty" json:"supports_ephemeral,omitempty"`

	// supports_from_snapshot: the substrate has a backing chain `from_snapshot:` restores from — vm
	// only (pod/k8s have no backing chains). validateEphemeral reads this instead of a word switch.
	SupportsFromSnapshot bool `yaml:"supports_from_snapshot,omitempty" json:"supports_from_snapshot,omitempty"`
}

type DeployTraitsCarrier interface {
	DeclaredDeployTraits() *DeployTraits
}

type DeployVenue struct {
	DeployName string `yaml:"deploy_name,omitempty" json:"deploy_name"`

	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`

	Substrate RawBody `yaml:"substrate,omitempty" json:"substrate,omitempty"`
}

type DeployVolume struct {
	Name string `yaml:"name,omitempty" json:"name"`

	Type string `yaml:"type,omitempty" json:"type,omitempty"`

	Host string `yaml:"host,omitempty" json:"host,omitempty"`

	Path string `yaml:"path,omitempty" json:"path,omitempty"`

	DataSeeded bool `yaml:"data_seeded,omitempty" json:"data_seeded,omitempty"`

	DataSource string `yaml:"data_source,omitempty" json:"data_source,omitempty"`
}

type DeploymentStatus struct {
	Kind SubstrateKind `yaml:"kind,omitempty" json:"kind"`

	Image string `yaml:"image,omitempty" json:"image"`

	ImageRef string `yaml:"image_ref,omitempty" json:"image_ref,omitempty"`

	Instance string `yaml:"instance,omitempty" json:"instance,omitempty"`

	Status string `yaml:"status,omitempty" json:"status"`

	Uptime string `yaml:"uptime,omitempty" json:"uptime,omitempty"`

	Container string `yaml:"container,omitempty" json:"container"`

	Ports []PortMapping `yaml:"ports,omitempty" json:"ports,omitempty"`

	Devices []string `yaml:"devices,omitempty" json:"devices,omitempty"`

	Tools []ToolStatus `yaml:"tools,omitempty" json:"tools,omitempty"`

	Volumes []string `yaml:"volumes,omitempty" json:"volumes,omitempty"`

	Network string `yaml:"network,omitempty" json:"network,omitempty"`

	Tunnel string `yaml:"tunnel,omitempty" json:"tunnel,omitempty"`

	Secrets []string `yaml:"secrets,omitempty" json:"secrets,omitempty"`

	RunMode string `yaml:"run_mode,omitempty" json:"run_mode"`

	Nested []*DeploymentStatus `yaml:"nested,omitempty" json:"nested,omitempty"`

	Source string `yaml:"source,omitempty" json:"source,omitempty"`
}

type DescentDescriptor struct {
	// transport: how the deploy chain descends INTO this node's substrate (DERIVED from the
	// declared venue + leaf_only by kit.DescentFromTraits):
	//
	//	none           — shares the parent venue; no hop (local, android).
	//	container-exec — enter the container by name (pod; podman/docker per engine).
	//	ssh            — an ssh hop into the guest (vm).
	//	reject         — unreachable via the deploy chain (k8s → use kubectl).
	Transport string `yaml:"transport,omitempty" json:"transport"`

	// host_rooted: the substrate's own ROOT executor runs directly on the host
	// (local), so the check runner uses rootExecutorForDeployNode, not a container chain.
	HostRooted bool `yaml:"host_rooted,omitempty" json:"host_rooted,omitempty"`

	// venue: how commands physically execute in this substrate's venue:
	//
	//	container — podman/docker exec into the container by name (pod).
	//	ssh       — an ssh hop into the guest (vm).
	//	shell     — the substrate's own root executor runs on the host (local; k8s host-side).
	//	parent    — reached via the parent's venue, no own executor (android).
	//	none      — external-in-place (zero value / group).
	Venue string `yaml:"venue,omitempty" json:"venue,omitempty"`

	// image_backed: the substrate runs a baked OCI image (pod).
	ImageBacked bool `yaml:"image_backed,omitempty" json:"image_backed,omitempty"`

	// image_context: the substrate composes over an image build context (pod overlay, k8s manifests).
	ImageContext bool `yaml:"image_context,omitempty" json:"image_context,omitempty"`

	// machine_venue: the substrate is a full machine with a system init (host/vm/local) — its
	// services render as systemd units, not a container init.
	MachineVenue bool `yaml:"machine_venue,omitempty" json:"machine_venue,omitempty"`

	// exclusive_venue: the substrate holds an exclusive host-resource lease boundary (vm).
	ExclusiveVenue bool `yaml:"exclusive_venue,omitempty" json:"exclusive_venue,omitempty"`

	// leaf_only: the substrate is a deploy-chain LEAF — it cannot be descended into (k8s).
	LeafOnly bool `yaml:"leaf_only,omitempty" json:"leaf_only,omitempty"`

	// bracketed_lifecycle: the substrate's Start/Stop accept direct-mode CLI opts (env/port/
	// volume/bind/no-auto-detect on Start, unmount on Stop) AND need the Q1 resource-arbiter
	// claim bracketed around the dispatch (pod). A substrate that manages its own venue
	// lifecycle + resource claim (vm, via `charly vm start`/`stop`) leaves this false.
	BracketedLifecycle bool `yaml:"bracketed_lifecycle,omitempty" json:"bracketed_lifecycle,omitempty"`

	// bed_target: the substrate is a valid `kind:check` bed target — pod/vm/local/android run a
	// disposable check bed; k8s (leaf_only) does not. validateCheckBeds reads this instead of
	// switching on the substrate word (the boundary-law incomplete-seam gate).
	BedTarget bool `yaml:"bed_target,omitempty" json:"bed_target,omitempty"`

	// supports_ephemeral: the substrate's Add/Del path wires the ephemeral register/teardown seam
	// (TTL timer + charly.yml persistence) — vm only today; pod/k8s reject `ephemeral: true` until
	// their Add/Del wire the same seam. validateEphemeral reads this instead of a substrate switch.
	SupportsEphemeral bool `yaml:"supports_ephemeral,omitempty" json:"supports_ephemeral,omitempty"`

	// supports_from_snapshot: the substrate has a backing chain `from_snapshot:` restores from — vm
	// only (pod/k8s have no backing chains). validateEphemeral reads this instead of a word switch.
	SupportsFromSnapshot bool `yaml:"supports_from_snapshot,omitempty" json:"supports_from_snapshot,omitempty"`
}

type DetectedDevices struct {
	GPU bool `yaml:"gpu,omitempty" json:"gpu"`

	AMDGPU bool `yaml:"amd_gpu,omitempty" json:"amd_gpu"`

	AMDGFXVersion string `yaml:"amd_gfx_version,omitempty" json:"amd_gfx_version"`

	RenderNode string `yaml:"render_node,omitempty" json:"render_node"`

	Devices []string `yaml:"devices,omitempty" json:"devices"`
}

type DevicePatternsReply struct {
	DevicePatterns []string `yaml:"device_patterns,omitempty" json:"device_patterns,omitempty"`

	GpuVendors map[string]string `yaml:"gpu_vendors,omitempty" json:"gpu_vendors,omitempty"`
}

type DevicePatternsRequest struct {
}

type Diagnostic struct {
	Severity string `yaml:"severity,omitempty" json:"severity,omitempty"`

	Message string `yaml:"message,omitempty" json:"message"`

	Path string `yaml:"path,omitempty" json:"path,omitempty"`
}

type Diagnostics struct {
	Items []Diagnostic `yaml:"items,omitempty" json:"items,omitempty"`
}

type DiscoverConfig []ScanSpec

type DiscoveredManifest struct {
	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`

	Manifest string `yaml:"manifest,omitempty" json:"manifest,omitempty"`

	RootDir string `yaml:"rootDir,omitempty" json:"rootDir,omitempty"`

	Docs []ParsedProject `yaml:"docs,omitempty" json:"docs,omitempty"`
}

type Distro struct {
	Inherits string `yaml:"inherits,omitempty" json:"inherits,omitempty"`

	InheritPackages bool `yaml:"inherit_packages,omitempty" json:"inherit_packages,omitempty"`

	Version string `yaml:"version,omitempty" json:"version,omitempty"`

	Bootstrap Bootstrap `yaml:"bootstrap,omitempty" json:"bootstrap,omitempty"`

	Workarounds []string `yaml:"workaround,omitempty" json:"workaround,omitempty"`

	Format map[string]*Format `yaml:"format,omitempty" json:"format,omitempty"`

	BaseUser *BaseUser `yaml:"base_user,omitempty" json:"base_user,omitempty"`

	Pacstrap *Pacstrap `yaml:"pacstrap,omitempty" json:"pacstrap,omitempty"`

	Debootstrap *Debootstrap `yaml:"debootstrap,omitempty" json:"debootstrap,omitempty"`

	AlpineBootstrap *AlpineBootstrap `yaml:"alpine_bootstrap,omitempty" json:"alpine_bootstrap,omitempty"`

	Bootloader *Bootloader `yaml:"bootloader,omitempty" json:"bootloader,omitempty"`

	Dnf *Dnf `yaml:"dnf,omitempty" json:"dnf,omitempty"`
}

type DistroDef = Distro

type DistroPackages struct {
	Package []PackageItem `yaml:"package,omitempty" json:"package,omitempty"`

	Copr []string `yaml:"copr,omitempty" json:"copr,omitempty"`

	Repo []RepoBlock `yaml:"repo,omitempty" json:"repo,omitempty"`

	Exclude []string `yaml:"exclude,omitempty" json:"exclude,omitempty"`

	Options []string `yaml:"option,omitempty" json:"option,omitempty"`

	Module []string `yaml:"module,omitempty" json:"module,omitempty"`

	AUR *AUR `yaml:"aur,omitempty" json:"aur,omitempty"`
}

type DistroResolveInput struct {
	Distro RawBody `yaml:"distro,omitempty" json:"distro"`
}

type DistroResolveReply struct {
	Resolved *ResolvedDistro `yaml:"resolved,omitempty" json:"resolved,omitempty"`
}

type Dnf struct {
	MaxParallelDownloads int64 `yaml:"max_parallel_downloads,omitempty" json:"max_parallel_downloads,omitempty"`

	Fastestmirror bool `yaml:"fastestmirror,omitempty" json:"fastestmirror,omitempty"`
}

type DoMode string

type DocParser interface {
	ParseDoc(doc *yaml.Node, t Threaded) (directives map[string]*yaml.Node, pp ParsedProject, err error)
}

type DocShape int