Module state 

EngineState — the single Mutex-guarded state object — plus the supporting types.

EngineState holds every mutable piece of engine flow state (task table, session table, prompts, token records, worker handles, resume table, per-task notifiers, resources, per-attempt output events, and the event log tail). It sits on the Domain side of the Data / Domain split and is unchanged by the Data-plane (output_store module) refactor.

Structs

AgentCtxEntry

One (task_id, attempt) entry of EngineState::agent_ctx — the materialized crate::core::agent_context::AgentContextView (Contract C, GH #20) and the effective mlua_swarm_schema::ContextPolicy AgentContextMiddleware already applied to it (projection-adapter ST5), folded into one struct (GH #23) so the two values — written together at the same single insert site — can no longer drift apart.

CapTokenRecord

Server-side counter/state holder paired 1:1 with a minted CapToken (keyed by nonce in EngineState.tokens). Tracks remaining uses, revocation, and — for Worker tokens — the task the token is bound to.

EngineState

The single Mutex-guarded blob of engine flow state, accessed only through Engine::with_state (see the R1-R4 discipline documented there).

OperatorSession

Persisted record of one attached Operator session: identity, role, heartbeat bookkeeping, owned tasks, and the OperatorKind cascade inputs plus registry IDs used to rebuild OperatorInfo on dispatch (see Engine::resolve_operator_info).

ResumeKey

Opaque handle identifying one query_senior suspend/resume cycle. Stored on TaskState.suspended_on and as the key of EngineState.pending_resumes.

ResumePending

Entry for a task suspended via query_senior, waiting to be resumed.

TaskSpec

Static task definition supplied to start_task: which agent runs it and the initial prompt/directive value.

TaskState

The full mutable record of one task: its static spec, current status, attempt counter, and bookkeeping timestamps. Cloned out of EngineState on every read (e.g. by read_task_state / poll_task).

Enums

CapTokenConsumeError

Why CapTokenRecord::consume refused to spend a use.

DispatchOutcome

Result of a dispatch_attempt_with call (or the conceptual outcome of a task attempt more broadly).

Event

Engine lifecycle event. Every event is both appended to EngineState.event_log_tail (in-process ring buffer) and broadcast on Engine::event_tx for live subscribers.

SubmitOutcome

GH #76 Skip tier: the completion tier a caller of crate::core::engine::Engine::submit_worker_result_trusted signals alongside its value. Sibling to DispatchOutcome (the engine-side outcome enum) — this one is the CALLER’s intent enum, whereas DispatchOutcome is the reduced outcome the engine derives from the completed attempt.

TaskStatus

Lifecycle state of a task. Pending is the only non-terminal, non-Suspended state before the first dispatch_attempt_with; Pass / Blocked / Cancelled are terminal.

Constants

SKIP_MARKER_KEY

Reserved sentinel key used by wrap_skip_marker / is_skip_marker to encode a DispatchOutcome::Skip payload as a plain serde_json::Value (GH #76 Skip tier: Skip tier). Documented as a reserved key on the wire: an ordinary worker payload MUST NOT contain a top-level object field named "__mse_skip".

Functions

is_skip_marker

Return true when v is an object with { "__mse_skip": true } set — the sentinel shape wrap_skip_marker produces. Used by the dispatcher (and the flow-ir binding boundary in future subtasks) to route a Skip completion out of the ordinary Pass/Blocked value path.

unwrap_skip_marker

If v is a skip-marker sentinel (see is_skip_marker), return the carried inner value cloned out of the "value" field (or Value::Null when the field is absent — a malformed sentinel is still a skip signal with no payload). Returns None otherwise, so the caller can fall back to the ordinary Pass/Blocked path.

wrap_skip_marker

Wrap v in the reserved { "__mse_skip": true, "value": v } sentinel shape produced by a SubmitOutcome::Skip submission and consumed by is_skip_marker / unwrap_skip_marker on the read side. See SKIP_MARKER_KEY for the reserved-key contract.

Type Aliases

EventStream

Receiver half of the engine-wide Event broadcast channel, obtained via Engine::subscribe.