Struct SessionRegistryV2 

pub struct SessionRegistryV2 { /* private fields */ }

Registry that manages the lifecycle of v2 execution sessions.

Clone is cheap — the inner Arc<RwLock<...>> is reference-counted.

Implementations

impl SessionRegistryV2

pub fn new( executor: Arc<Executor>, state_store: Arc<JsonFileStore>, card_store: Arc<FileCardStore>, scenarios_dir: PathBuf, ) -> Self

Create a new empty registry backed by executor, with the storage paths that will be injected into each spawned VM session.

The state_store / card_store / scenarios_dir mirror the legacy AppService resolution against the AppConfig::app_dir() layout, so a v2 caller produces the same on-disk side effects as a legacy caller.

pub async fn spawn_v2(&self, spec: SessionSpec) -> Result<SessionId, SpawnError>

Start a new v2 execution session, returning the SessionId immediately.

Execution proceeds in the background via tokio::spawn(driver_loop(...)). The caller receives the SessionId without waiting for execution to complete or for the first event (Invariant 6 / debt #40955).

Only algocline_core::execution::SpecKind::Run is supported in this subtask. Other variants return SpawnError::InvalidSpec. Subtask 3 will extend this to handle Advice and Eval through the full AppService path.

Errors

• SpawnError::Engine — the executor failed to start the session.
• SpawnError::InvalidSpec — the provided spec is malformed or uses an unsupported kind.

pub async fn state(&self, id: &SessionId) -> Result<ExecutionState, StateError>

Query the current ExecutionState of a session.

Errors

• StateError::NotFound — no session with the given id exists.

pub async fn resume( &self, id: &SessionId, payload: ResumePayload, ) -> Result<ResumeOutcome, ResumeError>

Resume a paused session by delivering LLM responses.

Errors

• ResumeError::NotFound — no session with the given id exists.
• ResumeError::NotPaused — the session is not in the Paused state.
• ResumeError::AlreadyCancelled — the session is already cancelled.

pub async fn cancel( &self, id: &SessionId, reason: CancelReason, ) -> Result<(), CancelError>

Request cooperative cancellation of a session.

Idempotent: returns Ok(()) for sessions already in a terminal state.

Errors

• CancelError::NotFound — no session with the given id exists.

pub fn observe( &self, id: &SessionId, ) -> Result<Box<dyn ObserverHandle>, ObserveError>

Subscribe to the progress event stream for a session.

This is a synchronous fn: broadcast::Sender::subscribe() is synchronous and does not perform I/O. Multiple concurrent subscribers each receive the full event stream independently (Crux R3).

Errors

• ObserveError::NotFound — no session with the given id exists, or try_read() experienced lock contention (write lock held by spawn). The contention path emits tracing::warn!(target = "session.observe", ...); callers cannot distinguish it from a true absent-session result.

pub async fn await_terminal( &self, id: &SessionId, ) -> Result<TerminalOutcome, AwaitError>

Await the terminal state of a session.

Polls the shared state until it reaches a terminal variant (Done, Cancelled, or Failed). The JoinHandle is never .abort()-ed (Crux R2).

Errors

• AwaitError::NotFound — no session with the given id exists.

pub fn spawn_gc_task(&self, ttl: Duration, interval: Duration)

Spawn a background GC task that periodically evicts idle, terminal sessions.

Mirrors the legacy SessionRegistry::spawn_gc_task contract (Crux #3 legacy parity) with two extensions:

1. Subscriber-count gate (Crux #1): a session is only evicted when bus_tx.receiver_count() == 0 at the moment the write guard is held, ensuring no use-after-eviction for active observers.
2. Parameterised interval (Crux #2): callers can supply a sub-second interval for test determinism without requiring tokio::time::pause.

The JoinHandle returned by tokio::spawn is intentionally dropped — the task runs until process exit (legacy fire-and-forget contract).

K-4 invariant

The sessions write guard is acquired once per GC tick. All operations inside the guard (receiver_count(), AtomicI64::load, HashMap::remove) are synchronous — no .await is called while the guard is held.

Trait Implementations

impl Clone for SessionRegistryV2

fn clone(&self) -> SessionRegistryV2

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.