scheduler

type Admission struct {
	Insert AdmissionGuard
	Start  AdmissionGuard
}

type AdmissionGuard func(controlsession.Binding, func()) error

type Completion struct {
	CleanupErr error
}

type Disposition struct {
	// Retained is every stored execution row, whatever its binding.
	Retained int64 `json:"retained"`
	// Started counts retained rows that carry a start marker. This build
	// never re-runs one: a restarted executor refuses a row it already
	// started instead of executing it a second time.
	Started int64 `json:"started"`
	// Queued counts retained rows that were accepted and persisted but
	// never started. They stay in the database; nothing replays them.
	Queued int64 `json:"queued"`
	// Quarantined counts unarchived execution rows the next start will
	// refuse to restore because their control session ended.
	Quarantined int64 `json:"quarantined"`
	// Archived counts explicit local operator dispositions. Original evidence
	// stays retained, but these runs cannot return to the execution queue.
	Archived int64 `json:"archived"`
	// Bindings counts the distinct control sessions the retained rows came
	// from, so an operator can see whether retained work accumulated over
	// several sessions.
	Bindings int `json:"bindings"`
	// RetainedTerminal counts terminal results this executor still holds
	// because it has not observed a durable acknowledgement for them.
	RetainedTerminal int64 `json:"retained_terminal"`
	// UnsentTerminal counts retained results no delivery attempt ever left
	// the executor for. The dispatcher cannot hold these.
	UnsentTerminal int64 `json:"unsent_terminal"`
	// RejectedTerminal counts retained results the dispatcher refused
	// permanently. They stay as evidence and are never retried.
	RejectedTerminal int64 `json:"rejected_terminal"`
	// Truncated reports that the retained rows come from more control
	// sessions than the inspection counts, so Bindings is a lower bound.
	// The counts of rows and results above are always exact.
	Truncated bool `json:"truncated"`
}

type FailedFunc func(context.Context, Spec, error) Completion

type Policy struct {
	EgressGrant *pb.EgressGrant
	FloorBW     int64
	CeilBW      int64
	Timeout     time.Duration
	Addresses   []string
	RequireICMP bool
	ListenUDP   bool
	ListenTCP   bool
	ListenSCION bool
}

type QueueLimits struct {
	Bytes int64
	Runs  int64
}

type RestoreEligibility func(controlsession.Binding) bool

type RetainedRun struct {
	Status        RetainedRunStatus
	DebugletID    uuid.UUID
	Binding       controlsession.Binding
	TransactionID string
	StartTime     time.Time
	StartedAt     time.Time
}

type RetainedRunStatus uint8

type RunInspection interface {
	// InspectRetainedRun reads one stored row, excluding rows that belong to
	// the supplied current binding. The reader is owned for the whole call:
	// caller cancellation bounds the caller's wait, never the backend's use of
	// its connection.
	InspectRetainedRun(ctx context.Context, id uuid.UUID, current controlsession.Binding) (RetainedRun, error)
}

type Scheduler interface {
	Insert(context.Context, Spec) error
	// CancelBound compares immutable run ownership atomically before cancellation.
	// It never cancels a later admission after observing an absent owner.
	CancelBound(context.Context, uuid.UUID, controlsession.Binding, error) (bool, error)
	// RegisterOnStart sets the callback function for when a debuglet should be started.
	RegisterOnStart(StartFunc)
	// RegisterFailed sets the callback function for when a debuglet fails to start or is not allowed to start anymore.
	RegisterFailed(FailedFunc)
	// StartLoop starts the loop that checks if any jobs are to be started and correspondingly calls the registered onStart function
	StartLoop(ctx context.Context) error
	// Shutdown closes new admission and joins owned active operations. Accepted
	// queued rows remain recoverable; existing insertion reservations complete.
	Shutdown(context.Context) error
}

type Spec struct {
	OutputVersion uint32
	Binding       controlsession.Binding
	DebugletID    uuid.UUID
	StartTime     *time.Time
	Args          []string
	Wasm          []byte
	Policy        Policy
	TransactionID string
}

type StartFunc func(context.Context, Spec) Completion

type TerminalAttempt struct {
	// Attempts counts the requests this pass actually sent.
	Attempts int64
	// Rejected reports a permanent refusal rather than a transient failure.
	Rejected bool
	Failure  error
}

type TerminalEvent struct {
	DebugletID   uuid.UUID
	Binding      controlsession.Binding
	ExitCode     int32
	ErrorMessage *string
	RecordedAt   time.Time
	// Attempts counts completed delivery attempts. Zero means the event was
	// retained but never sent; a positive count means the dispatcher may
	// already hold the same result, which its duplicate handling absorbs.
	Attempts      int64
	LastAttemptAt time.Time
	LastError     string
	// Rejected marks a cause the dispatcher will not accept on any retry. The
	// event stays as evidence and leaves the reconciliation set.
	Rejected bool
}

type TerminalRetention interface {
	// RecordTerminal retains the chosen result. It is idempotent under the run
	// identity and never rewrites an already retained result.
	RecordTerminal(context.Context, TerminalEvent) error
	// NoteTerminalFailure records what one failed delivery pass learned,
	// including its bounded cause. Zero attempts means the pass never reached
	// the dispatcher at all.
	NoteTerminalFailure(ctx context.Context, id uuid.UUID, binding controlsession.Binding, attempt TerminalAttempt) error
	// ReleaseTerminal ends retention after an acknowledgement was observed.
	ReleaseTerminal(ctx context.Context, id uuid.UUID, binding controlsession.Binding) error
	// ListRetainedTerminals reads at most limit events the given binding can
	// still deliver, oldest first. Rejected events and the events of other
	// sessions are excluded, so work no session can finish cannot crowd out
	// work that a session can.
	ListRetainedTerminals(ctx context.Context, binding controlsession.Binding, limit int64) ([]TerminalEvent, error)
}