lifecycle

type Config struct {
	// Interval is how often the reaper scans. Default: 1 minute.
	Interval time.Duration
	// MaxAge, when positive, ends any RUNNING run created longer ago than this
	// (WARDYN_RUN_MAX_AGE). Zero or negative is off.
	MaxAge time.Duration
	// Now overrides the wall clock. Nil means use real time.
	Now func() time.Time
	// TickLock, when non-nil, makes each tick single-flight across control
	// planes: TRY a cluster-wide lock, return a release func, or (nil, false)
	// if held elsewhere — then the tick is skipped, not queued. wardynd wires
	// a Postgres try-advisory-lock; kept as a func so lifecycle has no DB
	// dependency. Nil = ungated (single-process default; what tests use).
	TickLock func(ctx context.Context) (release func(), ok bool)
	// Sweeps, when non-nil, records each tick that does real work (the one that
	// won TickLock) as the idle_reaper sweep: an attempt when it starts and a
	// success only when it finishes without error. Nil records nothing.
	Sweeps *sweephealth.Tracker
}

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

type Recorder interface {
	Record(ctx context.Context, ev types.AuditEvent) error
}

type RunSummary struct {
	ID        uuid.UUID
	CreatedAt time.Time
	// AdmittedAt is when the run left the pool queue; zero for a run that never waited. The max age
	// counts from it, so a run that waited is not aged by its wait.
	AdmittedAt time.Time
	UpdatedAt  time.Time
	// PolicyAutoStopAfterSec: 0 or negative means never reap, positive is the
	// idle timeout in seconds. Store must JOIN to the policy table; zero is
	// intentional, not a missing join.
	PolicyAutoStopAfterSec int
	// Kept is a run kept after a control-plane outage whose agent still runs: the
	// max age still ends it, and idle reaping does not apply (its lost mark governs it).
	Kept bool
	// HasLifetimeCap is a run that carries agent_runs.lifetime_cap_at: the lease
	// sweep ends it at its cap (and the deployment's maximum age is one of the
	// limits that cap is measured from), so the max-age stop skips it. A run
	// from before that column keeps this reaper's max-age stop.
	HasLifetimeCap bool
}

type StopOutcome struct {
	// Applied is false when a concurrent kill/complete already moved the run
	// terminal, or the idleness guard no-op'd because updated_at advanced past
	// the snapshot (an active attach). Either way, no spurious run.autostop.
	Applied bool
	// Errors, when non-empty, are post-transition teardown/revocation failures
	// ("identity_error"/"broker_error": creds may still be live;
	// "teardown_error": sandbox may still be routable) that leave the run not
	// fully contained. Emitted as a distinct run.revoke/failure audit event,
	// mirroring handleKillRun/revokeRunCascade. Nil on a clean stop.
	Errors map[string]string
}

type Stopper interface {
	// StopRun must be idempotent: stopping an already-stopped run returns
	// ({Applied:false}, nil). notAfter is the snapshot's updated_at; the
	// transition is conditional on updated_at not having advanced past it, so
	// a run touched by an active attach since the snapshot is NOT stopped. A
	// non-nil error means the stop failed outright and the reaper logs/skips.
	StopRun(ctx context.Context, runID uuid.UUID, notAfter time.Time) (StopOutcome, error)

	// StopRunMaxAge stops a run that has outlived Config.MaxAge: the same
	// RUNNING->STOPPED transition and teardown as StopRun, guarded on the run's
	// created_at being at or before createdNotAfter instead of on idleness (and
	// ignoring open requests). Idempotent like StopRun.
	StopRunMaxAge(ctx context.Context, runID uuid.UUID, createdNotAfter time.Time) (StopOutcome, error)
}

type Store interface {
	// ListRunningWithPolicy returns RUNNING runs with their policy's
	// auto_stop_after_sec (0 if unattached/unset), plus the store's own clock
	// read once for the whole scan. The reaper measures idleness against that
	// clock, not its own: UpdatedAt is Postgres-stamped, so wardynd clock skew
	// vs. the database eats directly into TouchDebounce's 30s margin — enough
	// skew stops an actively-attached run and revokes its credentials, or
	// (skewed the other way) never reaps at all. A ZERO returned time means
	// the store has no clock (in-memory doubles), and the reaper falls back
	// to its own.
	ListRunningWithPolicy(ctx context.Context) ([]RunSummary, time.Time, error)
}