engine

type AppFacts struct {
	// PlacementState 是绑定状态位（” = 无绑定记录——自由调度非 blocked）。
	PlacementState string
	// Latest 是最近一条部署记录（零值 = 无部署）。
	Latest state.DeployRecord
	// LatestSucceeded 是最近一条 succeeded 部署（零值 = 无有效版本）。
	LatestSucceeded state.DeployRecord
}

type Clock interface {
	Now() time.Time
}

type Config struct {
	// ReleaseTimeout 是 L2 看门狗预算（默认 300s；有效值 ≥ health 预算）。
	ReleaseTimeout time.Duration
	// ObserveWindow 是 L3 观察窗时长（默认 60s）。
	ObserveWindow time.Duration
	// UnstableReplicasBelow 是副本水位的持续不足判定时长（默认 10s，
	// release-semantics §2.2 L3 信号）。
	ReplicasBelowFor time.Duration
	// PollInterval 是引擎轮询周期（默认 2s）。
	PollInterval time.Duration
	// DriftInterval 是运行域漂移检测扫描周期（默认 30s，可配
	// engine.drift_interval_seconds；D11：检测默认开）。
	DriftInterval time.Duration
}

type DriftReport struct {
	App string `json:"app"`
	// DesiredDeployment 是期望态来源部署（空 = 无成功部署记录，无从判定）。
	DesiredDeployment string         `json:"desired_deployment,omitempty"`
	Drifted           bool           `json:"drifted"`
	Services          []ServiceDrift `json:"services,omitempty"`
}

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

type ErrIllegalTransition struct {
	From Phase
	To   Phase
}

type FieldDiff struct {
	Field    string `json:"field"`
	Expected string `json:"expected"`
	Actual   string `json:"actual"`
}

type HealthcheckSpec struct {
	Test        []string      `json:"test"`
	Interval    time.Duration `json:"interval"`
	Timeout     time.Duration `json:"timeout"`
	Retries     uint64        `json:"retries"`
	StartPeriod time.Duration `json:"start_period"`
}

type ImageChecker interface {
	// ImageDigest 返回镜像本机 ID（`sha256:<hex>`）；缺失返回
	// ErrImageMissing。
	ImageDigest(ctx context.Context, ref string) (string, error)
}

type MountSpec struct {
	// VolumeName 是平台卷注册表的 docker 卷名（fleetly-<app>-<key>-<id8>）。
	VolumeName string `json:"volume"`
	Target     string `json:"target"`
	ReadOnly   bool   `json:"read_only,omitempty"`
}

type NetworkAttach struct {
	Name string `json:"name"`
	// Aliases 是网络内别名（= compose 服务名，app 内短名互访）。
	Aliases []string `json:"aliases,omitempty"`
}

type Phase string

type PlacementResolver interface {
	Resolve(ctx context.Context, in placement.Input) (placement.Decision, error)
	Apply(ctx context.Context, in placement.Input) (placement.Decision, error)
	Preflight(ctx context.Context, appID string) error
}

type Plan struct {
	// Services 按服务名字典序（对账与快照确定性）。
	Services []ServiceSpec
	// EnvSnapshotHash 是 env 三层合并结果快照哈希（key:sha256+来源；
	// 值明文永不进哈希输入）。
	EnvSnapshotHash string
	// DesiredHash 是部署级期望态哈希（spec + env + 各服务哈希合成）。
	DesiredHash string
	// DesiredSpecJSON 是 []ServiceSpec 的 canonical JSON（密文化的快照明文
	// 形态——归位/重放的执行依据）。
	DesiredSpecJSON []byte
	// Warnings 是规划期警告（W_ENV_PLATFORM_OVERRIDE 等）。
	Warnings []compose.Warning
}

type PlanInput struct {
	AppID   string
	AppName string
	// DeploymentID 是发布归属（服务 label fleetly.deployment）。
	DeploymentID string
	// Spec 是归一化 compose（daemon 侧重载，二次校验防御）。
	Spec *compose.Spec
	// FileEnv / ComposeEnv 是 services.* 的文件层明文（extractServiceEnvs）。
	FileEnv    map[string]map[string]string
	ComposeEnv map[string]map[string]string
	// PlatformEnv 是已生效（effective）平台 env（三层合并的第三层输入；
	// pending 不参与合并——「随下次部署生效」由部署成功后的 promote 承载）。
	PlatformEnv []envlayer.PlatformVar
	// Images 是服务 → digest 钉定镜像引用（building 阶段产出）。
	Images map[string]string
	// Decision 是放置裁决（绑定约束编译结果）。
	Decision placement.Decision
	Volumes  []state.Volume
}

type PostDeployHook func(rec state.DeployRecord)

type ResourcesSpec struct {
	NanoCPUs    int64 `json:"nano_cpus,omitempty"`
	MemoryBytes int64 `json:"memory_bytes,omitempty"`
}

type RestartPolicySpec struct {
	Condition   string        `json:"condition"`
	Delay       time.Duration `json:"delay,omitempty"`
	MaxAttempts uint64        `json:"max_attempts,omitempty"`
	Window      time.Duration `json:"window,omitempty"`
}

type RollbackInput struct {
	// AppName 是 compose 应用名。
	AppName string
	// TargetRevisionID 是回滚目标版本快照；空 = 最近一次成功部署的版本
	//（`fleetly rollback <app>` 缺省回退一版）。
	TargetRevisionID string
	// Actor 是审计操作主体（human/ai_agent；CLI 直连为 human）。空按
	// human 兜底（审计列非空约束）。
	Actor string
}

type RoutePublishInput struct {
	AppID    string
	AppName  string
	Services []RouteServiceSpec
}

type RoutePublisher interface {
	PublishRoutes(ctx context.Context, in RoutePublishInput) error
}

type RouteServiceSpec struct {
	Service string
	// Port 是后端端口（compose expose 首端口）。
	Port string
	// Domains 是归一化域名集。
	Domains []string
}

type SecretMount struct {
	// SecretName 是 Swarm secret 名（fleetly-<app>-<name>-<hash8>）。
	SecretName string `json:"secret"`
	// Target 是容器内挂载文件路径（/run/secrets/<compose 名>）。
	Target string `json:"target"`
}

type ServiceDrift struct {
	Service string      `json:"service"`
	Drifted bool        `json:"drifted"`
	Missing bool        `json:"missing,omitempty"`
	Extra   bool        `json:"extra,omitempty"`
	Diff    []FieldDiff `json:"diff,omitempty"`
}

type ServiceSpec struct {
	// Name 是 Swarm 服务名（fleetly-<app>-<service>，naming.ServiceName）。
	Name string `json:"name"`
	// Image 是 digest 钉定引用（`repo@sha256:...`，D9）。
	Image   string   `json:"image"`
	Command []string `json:"command,omitempty"`
	// Env 是合并后的注入环境（KEY=VALUE，按 key 字典序；值明文只存活于
	// 本结构与密文快照，不进日志/事件/审计）。
	Env []string `json:"env,omitempty"`
	// ServiceLabels 是服务级 label（naming.ServiceLabels 最小集 +
	// fleetly.desired-hash；service-label 变更不触发任务重建，Spike B2）。
	ServiceLabels map[string]string `json:"service_labels,omitempty"`
	// ContainerLabels 是任务容器 label（naming.ContainerLabels：仅
	// fleetly.app——跨部署稳定，归位零任务替换的前提，Spike B2）。
	ContainerLabels map[string]string `json:"container_labels,omitempty"`
	// Global 是 global 模式（compose deploy.mode=global）；false = replicated。
	Global bool `json:"global,omitempty"`
	// Replicas 是期望副本（replicated 模式；0 = scale-0 保留现场）。
	Replicas uint64 `json:"replicas"`
	// Networks 是服务接入网络（per-app 专属网络 + 别名 = compose 服务名）。
	Networks []NetworkAttach `json:"networks,omitempty"`
	// Mounts 是命名卷挂载（docker 卷名经卷注册表映射）。
	Mounts []MountSpec `json:"mounts,omitempty"`
	// Secrets 是 Swarm secret 挂载（file target = compose 名）。
	Secrets []SecretMount `json:"secrets,omitempty"`
	// Healthcheck 为 nil = health_gate=none（健康门退化为退出/副本水位）。
	Healthcheck *HealthcheckSpec `json:"healthcheck,omitempty"`
	// UpdateOrder 是更新顺序（start-first 默认；有卷/固定端口/global 强制
	// stop-first——组合裁决在规划层，适配器照用）。
	UpdateOrder string `json:"update_order"`
	// UpdateParallelism / UpdateDelay 照用 compose（parallelism 缺省 1）。
	UpdateParallelism uint64        `json:"update_parallelism"`
	UpdateDelay       time.Duration `json:"update_delay,omitempty"`
	// RestartPolicy 为 nil 时适配器补平台缺省（condition=any / delay=5s，
	// architecture §2.5 运行期语义）。
	RestartPolicy *RestartPolicySpec `json:"restart_policy,omitempty"`
	Resources     *ResourcesSpec     `json:"resources,omitempty"`
	// Constraints 是放置约束（绑定钉住编译 + compose 声明的
	// node.labels.fleetly.* 约束）。
	Constraints []string `json:"constraints,omitempty"`
	StopSignal  string   `json:"stop_signal,omitempty"`
	// StopGracePeriod ≤0 = 底座缺省（compose stop_grace_period 照用）。
	StopGracePeriod time.Duration `json:"stop_grace_period,omitempty"`
}

type ServiceState struct {
	Name string
	// Version 是底座对象版本（乐观令牌；诊断用——服务写经适配器内部取版
	// 本，引擎不做跨调用令牌传递，避免写前直读令牌陈旧化）。
	Version uint64
	Labels  map[string]string
	// DesiredHash 是服务 label 里的期望态哈希（” = 非平台写或旧形态）。
	DesiredHash string
	// Image 是当前 spec 镜像引用。
	Image string
	// Replicas 是期望副本数（replicated；global 服务为 0）。
	Replicas uint64
	// UpdateState / UpdateMessage 逐字镜像底座 UpdateStatus
	//（”/updating/paused/completed，Spike B：更新失败归 paused+Message）。
	UpdateState   string
	UpdateMessage string

	// ── 运行域漂移反解字段（T2.13；与 ServiceSpec 同构，由适配器填充）──
	Command         []string
	Env             []string
	ContainerLabels map[string]string
	Global          bool
	Networks        []NetworkAttach
	Mounts          []MountSpec
	Secrets         []SecretMount
	Healthcheck     *HealthcheckSpec
	RestartPolicy   *RestartPolicySpec
	Resources       *ResourcesSpec
	Constraints     []string
	StopSignal      string
	StopGracePeriod time.Duration
}

type Substrate interface {
	// SwarmReady 确认本机为 active swarm manager；未 init 返回可判别错误
	//（errors.Is(err, ErrNotSwarmReady)）。
	SwarmReady(ctx context.Context) error
	// NetworkEnsure 确认 overlay 网络存在（幂等；缺失创建）。
	NetworkEnsure(ctx context.Context, name string) error
	// ServiceInspect 按名取服务实况；缺失返回 ErrServiceNotFound。
	ServiceInspect(ctx context.Context, name string) (ServiceState, error)
	// ServiceCreate 创建服务（幂等性由调用方对账保证：仅缺失时调用）。
	ServiceCreate(ctx context.Context, spec ServiceSpec) error
	// ServiceUpdate 以乐观令牌推进服务到目标形态。适配器内部读版本并短
	// 重试并发冲突；ForceUpdate 恒不递增（归位零成本纪律，Spike B2）。
	ServiceUpdate(ctx context.Context, name string, spec ServiceSpec) error
	// ServiceRemove 删除服务（省略=删除语义；幂等：缺失视为成功）。
	ServiceRemove(ctx context.Context, name string) error
	// ServiceList 按 label 选择器返回服务（managed+app 前缀过滤）。
	ServiceList(ctx context.Context, labels map[string]string) ([]ServiceState, error)
	// TaskList 返回服务的全部任务（含历史；观测轮询的数据源）。
	TaskList(ctx context.Context, service string) ([]TaskState, error)
}

type TaskState struct {
	ID   string
	Slot int
	// State 逐字镜像底座任务状态（new/pending/running/failed/complete/
	// shutdown/rejected/...）。
	State string
	// DesiredState 是期望态（running/remove/...）——旧任务下线判据。
	DesiredState string
	// Err 是任务失败原因（逐字；health 判定归 E_HEALTH_TIMEOUT 的来源）。
	Err string
	// Timestamp 是任务状态时间戳。
	Timestamp time.Time
	// Image 是任务 spec 镜像引用（新旧版本判据：与目标 digest 比对）。
	Image string
}