scale

type Action string

type Budget struct {
	HostTotal  uint64 // total host resource
	HostFree   uint64 // measured-free right now
	Reserved   uint64 // everything NOT this service: control plane + edge + safety floor + OTHER apps' desired replicas
	FreeFloor  uint64 // keep at least this much free (applied to the measured budget)
	PerReplica uint64 // this service's per-replica reservation (required, non-zero)
	Current    int    // this service's current replica count
}

type CapacityInput struct {
	Mem Budget
	CPU Budget

	PolicyMax          int    // operator's configured max_replicas
	PerReplicaMemFloor uint64 // an implausibly small per-replica mem reservation is rejected
	NearOOMFreeBytes   uint64 // host mem free below this → effective_max collapses to 1
}

type Config struct {
	Store        *Store
	Alerts       *alertstore.Store // nil → refusals are logged only
	Snap         func() *monitor.Snapshot
	Sem          *dockerexec.Semaphore
	Scaler       Scaler
	Edge         EdgeReconciler // optional
	Reserves     Reserves
	Log          *slog.Logger
	Interval     time.Duration
	WritePlaneOK bool
	HostCPUMilli uint64                                        // total host CPU (milli); 0 disables the CPU budget
	IsCandidate  func(app, service string) (ServiceSpec, bool) // C1–C6 from compose; nil → trust the policy opt-in
	// EdgeStats returns the edge-measured p95 latency (ms) and request rate (req/s) for a service
	// over the rolling window, plus whether ANY request was sampled in it. It backs source:edge
	// metrics. nil = no managed edge on this host → source:edge metrics are OMITTED (inert), so they
	// neither help nor pin scaling.
	EdgeStats func(app, service string) (p95Ms, reqPerSec float64, present bool)
	// EdgeLive reports whether the edge is delivering access logs at all right now (any service).
	// It lets edgeSignal tell a genuinely-idle service (edge live, no samples → may scale down) from
	// a blind window (enable-time lag / broken capture → HOLD, never shed on data we don't have).
	// Wired together with EdgeStats (both set, or both nil).
	EdgeLive func() bool
	// Held returns the set of operator-HELD services (a manual stop / "pause auto-restart"). A held
	// service is skipped entirely each tick — never reconciled, scaled, or reserved-for — so a
	// service the operator deliberately stopped is not relaunched by the scaler. Read once per tick.
	// nil → nothing held.
	Held func() map[Key]bool
	// CircuitOpen returns services whose self-heal circuit is OPEN (self-heal gave up on a crash loop
	// and is paging instead of restarting). The scaler must NOT relaunch them — reconciling a crashed
	// replica back up would re-arm exactly the loop the breaker exists to stop. Read once per tick.
	CircuitOpen func() map[Key]bool
	// BusyApps returns apps holding a self-heal expected_down lease (an operator lifecycle/deploy
	// action is in flight). The scaler skips their services meanwhile — it must not fight the write
	// plane, and this also closes the brief window during an operator STOP before its hold row lands
	// (self-heal holds the lease until after the hold is written). Read once per tick.
	BusyApps func() map[string]bool
	Now      func() int64
}

type Decision struct {
	Target int
	Action Action
	Reason string
	Next   State
}

type EdgeReconciler interface {
	ReconcilePool(ctx context.Context, app, service string, replicas int) error
}

type Key struct{ App, Service string }

type MetricSpec struct {
	Name   string  `json:"name"`
	Source string  `json:"source"` // "ops" (app queue depth) | "edge" (Mooring-measured latency / req-rate)
	Select string  `json:"select,omitempty"`
	Up     float64 `json:"up"`
	Down   float64 `json:"down"`
}

type Metrics struct {
	CPUMeanPct float64
	MemMaxPct  float64
	AllHealthy bool
	Signals    []Signal // custom per-service signals, keyed by name
}

type Policy struct {
	Min, Max         int
	UpCPUPct         float64
	UpMemPct         float64
	DownCPUPct       float64
	DownMemPct       float64
	BreachForSecs    int64
	CooldownUpSecs   int64
	CooldownDownSecs int64
	Signals          []SignalPolicy // custom signals (additive; CPU/mem unchanged)
}

type PolicyRow struct {
	Policy
	Enabled       bool
	PerReplicaMem uint64
	PerReplicaCPU uint64
	Metrics       []MetricSpec // custom scaling signals (source + thresholds); mirrored into Policy.Signals
}

type Reserves struct {
	MemReserveBytes    uint64 // control plane + edge + safety floor (memory)
	CPUReserveMilli    uint64 // control plane + edge (cpu)
	MemFreeFloor       uint64 // keep at least this much memory free (measured budget)
	CPUFreeFloor       uint64
	NearOOMFreeBytes   uint64
	PerReplicaMemFloor uint64
}

type Scaler interface {
	Scale(ctx context.Context, app, service string, replicas int) error
}

type ServiceSpec struct {
	Name                string
	EdgeUpstream        bool // C1: an edge HTTP upstream with a known internal port
	L4Upstream          bool // C1 (alt): a managed L4 (TCP/UDP) upstream — fronted by an edge l4_route, replicas internal-only
	FixedHostPort       bool // C2 (disqualifies): publishes a fixed host port the LB does NOT own
	RWVolume            bool // C3 (disqualifies): has an exclusive read-write volume
	Stateful            bool // C4 (disqualifies): a DB/broker/coordination store
	IdentityPlaceholder bool // C5 (disqualifies): a deploy-time identity (node cookie/name/seed/host-bound port)
	StatelessContract   bool // C6: honors the stateless restart contract (operator attests)
	OptedIn             bool // C7: the operator explicitly enabled scaling for this service
}

type Signal struct {
	Name    string
	Value   float64
	Present bool
}

type SignalPolicy struct {
	Name string
	Up   float64
	Down float64
}

type State struct {
	Replicas    int
	BreachSince int64 // unix sec; when the current up-breach started (0 = not breaching)
	LastChange  int64 // unix sec; last scale action (for the cooldowns)
}

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

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