Struct SpeculationEngine 

pub struct SpeculationEngine { /* private fields */ }

Speculative execution engine.

Holds a reference to the underlying executor, the shared cache, and the active configuration. Create one instance per agent session and share via Arc.

Examples

use std::sync::Arc;
use zeph_config::tools::SpeculativeConfig;
use zeph_core::agent::speculative::SpeculationEngine;

let config = SpeculativeConfig::default(); // mode = off
let engine = SpeculationEngine::new(executor, config);

Implementations

impl SpeculationEngine

pub fn new( executor: Arc<dyn ErasedToolExecutor>, config: SpeculativeConfig, ) -> Self

Create a new engine with the given executor and config.

pub fn new_with_supervisor( executor: Arc<dyn ErasedToolExecutor>, config: SpeculativeConfig, supervisor: Option<Arc<TaskSupervisor>>, ) -> Self

Create a new engine with an optional session-level supervisor for task registration.

When supervisor is Some, the background sweeper and speculative dispatch tasks are registered for observability and graceful shutdown. Pass None in test harnesses.

pub fn mode(&self) -> SpeculationMode

Current speculation mode.

pub fn is_active(&self) -> bool

Returns true when speculation is not Off.

pub fn try_dispatch( &self, prediction: &Prediction, trust_level: SkillTrustLevel, ) -> bool

Try to dispatch prediction speculatively.

Returns false when the call is skipped (not speculatable, trust gate, confirmation gate, or circuit-breaker). Returns true when the handle was inserted in the cache.

The confirmation check is performed via requires_confirmation_erased — a pure policy query that does not execute the tool (fixes C1: no double side-effects).

pub async fn try_commit( &self, call: &ToolCall, ) -> Option<Result<Option<ToolOutput>, ToolError>>

Attempt to commit a speculative handle for call.

If a matching handle exists (same tool_id + args_hash), awaits its result and returns it. If no match, returns None — caller should fall through to normal dispatch.

pub fn cancel_for(&self, tool_id: &ToolName)

Cancel and remove the in-flight handle for tool_id, if any.

Performs an actual cache lookup and task abort (fixes C3: was metrics-only no-op).

pub fn end_turn(&self) -> SpeculativeMetrics

Cancel all in-flight handles at turn boundary and return metrics snapshot.

pub fn metrics_snapshot(&self) -> SpeculativeMetrics

Snapshot current metrics without resetting.

Trait Implementations

impl Drop for SpeculationEngine

fn drop(&mut self)

Executes the destructor for this type.