lifecycle

type Config struct {
	// Interval is how often the reaper scans. Default: 1 minute.
	Interval time.Duration
	// Now overrides the wall clock. Nil means use real time.
	// (overridable in tests, mirrors embedded.Provider's now func idiom)
	Now func() time.Time
	// TickLock, when non-nil, makes each tick single-flight across control
	// planes: it must TRY to take a cluster-wide lock and return a release func,
	// or (nil, false) when someone else holds it — in which case the tick is
	// skipped, not queued. wardynd wires a Postgres try-advisory-lock
	// (db.TryAdvisoryLock, key db.ReaperAdvisoryLockKey); it stays a func here so
	// lifecycle keeps no database dependency, like Store/Stopper/Recorder.
	//
	// Nil = ungated, the single-process default (and what tests drive Tick with).
	TickLock func(ctx context.Context) (release func(), ok bool)
}

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
	UpdatedAt time.Time
	// PolicyAutoStopAfterSec is the value from the run's attached policy spec.
	// Semantics (see package doc): 0 means DISABLED (never reap), a NEGATIVE value
	// also means "never reap", and a POSITIVE value is the idle timeout in seconds.
	// The Store must JOIN to the policy table and surface this field; a zero value
	// is intentional (a run with no auto-stop configured is never reaped, not a
	// missing join).
	PolicyAutoStopAfterSec int
}

type StopOutcome struct {
	// Applied reports whether the stop actually transitioned the run from RUNNING
	// to STOPPED. It is false when a concurrent kill/complete had already moved the
	// run terminal, OR when the idleness guard no-op'd because the run's updated_at
	// advanced past the reaper's snapshot (an active `wardyn attach` touched it
	// after the scan — finding N3). Either way the reaper must NOT emit a spurious
	// run.autostop (finding #1).
	Applied bool
	// Errors, when non-empty, carries the teardown/revocation failures that
	// occurred AFTER the stop transition won (Applied=true) but which left the run
	// not fully contained: "identity_error" / "broker_error" (the run token or
	// minted broker creds may still be live — finding N1), and "teardown_error"
	// (the sandbox may still be routable). The reaper emits these as a distinct
	// run.revoke/failure audit event so the live-credential/live-sandbox window is
	// visible, mirroring handleKillRun/revokeRunCascade. Nil on a clean stop.
	Errors map[string]string
}

type Stopper interface {
	// StopRun gracefully stops the run identified by runID. Implementations must
	// be idempotent: stopping an already-stopped run returns ({Applied:false}, nil).
	//
	// notAfter is the run's updated_at from the reaper's tick snapshot: the stop
	// transition must be conditional on updated_at not having advanced past it, so
	// a run an active attach touched after the snapshot is NOT stopped (finding N3).
	//
	// The returned StopOutcome reports whether the transition applied and any
	// post-transition teardown/revocation failures. A non-nil error means the stop
	// failed outright; the outcome is meaningless and the reaper logs and skips.
	StopRun(ctx context.Context, runID uuid.UUID, notAfter time.Time) (StopOutcome, error)
}

type Store interface {
	// ListRunningWithPolicy returns all runs currently in state RUNNING
	// together with the auto_stop_after_sec value from their attached policy
	// (0 when no policy is attached or the policy field is unset).
	ListRunningWithPolicy(ctx context.Context) ([]RunSummary, error)
}