Scheduler

This page defines the current contract for Holon's scheduler: what inputs it consumes, how it derives posture and runnability, and what decisions it emits. It also documents the additive protocol transition layer that wraps scheduler decisions in atomic transactions with replay protection, explicit activation ownership, terminal settlement, and a public diagnostic event stream.

Last verified: 2026-08-18 against src/runtime/scheduler.rs, src/runtime/scheduler_executor.rs, src/runtime/waiting.rs, src/runtime/closure.rs, src/runtime/turn/execution.rs, src/runtime_db/transitions.rs, src/runtime_event.rs, and src/types.rs.

Source RFCs

• Runtime Scheduler Contract
• Scheduler–WorkItem Unified Execution Protocol
• Scheduler Cutover Simplification
• Scheduler Wait State And Recoverable Agent Continuation
• Waiting Plane And Reactivation
• Continuation Trigger
• Work Item Centered Agent Runtime
• Agent Activation, Settlement, and Dispatch — historical activation/settlement design; superseded where the unified protocol assigns current authority

Core model

The scheduler is the runtime component that answers: given the current agent state, what should happen next?

It consumes a SchedulerProjection — a snapshot assembled from:

The projection is a read-only snapshot; the scheduler never mutates durable state directly. Decisions are emitted and handed to the executor.

Scheduler inputs (SchedulerInput)

Scheduler decisions (SchedulerDecisionKind)

Each decision carries metadata: reason, model_reentry, liveness_only, work_item_id, task_id, and evidence.

Decision flow

                    SchedulerInput
                         │
                         ▼
              ┌─────────────────────┐
              │ Status == Stopped?  │──Yes──► Stop
              └─────────┬───────────┘
                        │ No
                        ▼
              ┌─────────────────────┐
              │ Turn in progress?   │──Yes──► Noop
              └─────────┬───────────┘
                        │ No
                        ▼
         ┌──────────────────────────┐
         │ Queue has pending input? │──Yes──► StartModelTurn
         └──────────────┬───────────┘        (or ReduceMessageOnly)
                        │ No
                        ▼
         ┌──────────────────────────┐
         │ Runnable WorkItem?       │──Yes──► EmitSystemTick
         └──────────────┬───────────┘        (ContinueActive)
                        │ No
                        ▼
         ┌──────────────────────────┐
         │ Active wait condition?   │──Yes──► WaitFor{Task,
         └──────────────┬───────────┘         External,Timer,Operator}
                        │ No
                        ▼
                      Sleep

WorkItem scheduling states

WorkItems flow through scheduling states that the scheduler consumes:

Wake/sleep boundary

• Sleep is an internal scheduler decision after turn closure. The scheduler decides whether the agent truly becomes Asleep or continues with queued work.
• WaitFor records explicit wait state and then yields the turn. It is the model-facing path for task, external, and operator waits.
• StayIdle means the agent is already asleep and the scheduler has nothing to do; this is distinct from Sleep (the initial transition).
• EmitSystemTick injects an internal follow-up message to re-enter the model when a runnable WorkItem is found at an idle boundary.
• When CompleteWorkItem promotion ends a turn, any remaining runnable WorkItem is resumed by the same work-queue SystemTick path.
• Wake hints are liveness signals: they tell the scheduler to re-evaluate but do not themselves carry content for the model.
• Duplicate suppression uses idempotency keys to prevent redundant system ticks for the same wake hint or continue-active signal.

Protocol transition layer

The scheduler wraps each boundary in an atomic QueueTransitionCommand transaction that can simultaneously:

1. commit the queue operation (admit, claim, or enqueue);
2. update the agent state projection;
3. persist message evidence, transcript entries, and audit events;
4. bind a canonical activation owner and execution disposition; and
5. persist settlement, recovery, and delivery evidence.

All effects commit in the same SQLite transaction. If the transaction fails or the CAS does not match, no partial queue, activation, settlement, or delivery state is left behind.

The canonical scheduler is the only runtime engine. Queue, WorkItem, wait, task, Turn, transcript, brief, delivery, activation, settlement, and execution facts share one authority and transaction path.

The accepted transition contract retires runtime manifest/preflight gates, per-scenario authority, automatic hard-blocker rollback, production shadow comparison, the legacy engine, and the runtime engine selector. Historical selector configuration is not a runtime input.

Integration points

QueueTransitionCommand is committed at every scheduler boundary. Each boundary records the canonical facts required by the next boundary:

The semantic decision plane is not part of production admission. Its production module and fixtures have been removed. Deterministic structural binding and the canonical protocol retain all state-transition control.

Public diagnostic event stream

The scheduler emits a typed SchedulerDiagnosticAuditEvent for every decision that passes through append_scheduler_decision. This event carries:

The event is emitted via RuntimeEventKind::SchedulerDiagnostic alongside the legacy scheduler_decision audit event. Both are persisted in the same transaction as the scheduler decision. The typed event is the public observability surface; the legacy audit event remains for backward compatibility.

Scheduling advisories

SchedulingAdvisory is an internal, non-authoritative warning system that detects potential scheduler state mismatches: idle posture with runnable work, weak external wait recoverability, unrecoverable blocked WorkItems, and similar conditions. Advisories are appended as scheduling_advisory audit events with deduplication against recent events.

Advisories are not diagnostics in the diagnostic event stream sense. They are internal hints for debugging and operational awareness; the deterministic scheduler projection and posture derivation remain the sole authority for scheduling decisions.

Known gaps

• SchedulerDecisionKind intentionally has more variants than the coarse RFC posture labels. The RFC posture is the stable turn-end vocabulary; decision variants are concrete runtime actions and duplicate-suppression outcomes.
• Scheduler release acceptance validates atomicity, restart, bounded concurrent load, fault handling, and FIFO WorkItem projection outside the runtime authority path. It is not a calibrated production SLO or a substitute for deployment-specific soak and capacity testing.