Skip to main content

deq_runtime/controller/
jit_controller.rs

1use crate::bin::{self, check_model, check_model_type, error_model, error_model_type};
2use crate::coordinator::CoordinatorClient;
3use crate::jit::{self, jit_compiler::JitCompiler};
4use crate::misc::sync::TaskCounter;
5use hashbrown::{HashMap, HashSet};
6use serde::{Deserialize, Serialize};
7use std::hash::{Hash, Hasher};
8use std::sync::Arc;
9use std::sync::atomic::{AtomicU64, Ordering};
10#[cfg(feature = "cli")]
11use structdoc::StructDoc;
12use tokio::sync::RwLock;
13use tokio_util::sync::CancellationToken;
14
15include!("../proto/deq.controller.jit_controller.rs");
16
17#[derive(Debug, Clone, Serialize, Deserialize)]
18#[cfg_attr(feature = "cli", derive(StructDoc))]
19#[serde(deny_unknown_fields)]
20pub struct JitControllerConfig {
21    /// Optional path to a `.deq.jit` library file. When omitted the controller
22    /// starts with an empty library and the caller is expected to load
23    /// libraries dynamically via the `load_library` RPC (this is the typical
24    /// path for in-process Python use).
25    #[serde(default)]
26    pub filepath: Option<String>,
27    /// cache the generated deq-bin and try to reuse them instead of creating new ones.
28    /// this will help the coordinator to find cached decoder results and speed up decoding, but
29    /// may cause memory bloat if there are many unique check models and error models.
30    #[serde(default = "default_cache_enabled")]
31    pub cache_enabled: bool,
32}
33
34fn default_cache_enabled() -> bool {
35    true
36}
37
38pub struct JitController {
39    pub config: JitControllerConfig,
40    pub compiler: Arc<JitCompiler>,
41    coordinator: RwLock<Option<CoordinatorClient>>,
42    type_cache: RwLock<TypeCache>,
43    next_ctype: AtomicU64,
44    next_etype: AtomicU64,
45    terminal_etypes: RwLock<HashMap<u64, u64>>,
46    library: crate::jit::JitLibrary,
47    /// Executed gadgets whose outcomes have not yet been submitted for decoding.
48    undecoded_gids: RwLock<HashSet<u64>>,
49    /// Cancelled on reset()/drop to abort pending error-model and batch tasks.
50    cancellation: RwLock<CancellationToken>,
51    /// Tracks active spawned tasks; reset() waits for all to finish.
52    task_counter: Arc<TaskCounter>,
53}
54
55impl JitController {
56    pub fn new(config: serde_json::Value) -> Arc<Self> {
57        let config: JitControllerConfig = serde_json::from_value(config).unwrap();
58        let library: crate::jit::JitLibrary = if let Some(filepath) = config.filepath.as_ref() {
59            let data = std::fs::read(filepath).unwrap();
60            prost::Message::decode(&mut data.as_slice()).unwrap()
61        } else {
62            crate::jit::JitLibrary::default()
63        };
64        let compiler = JitCompiler::new();
65        Arc::new(Self {
66            config,
67            compiler,
68            coordinator: RwLock::new(None),
69            type_cache: RwLock::new(TypeCache::new()),
70            next_ctype: AtomicU64::new(1),
71            next_etype: AtomicU64::new(1),
72            terminal_etypes: RwLock::new(HashMap::new()),
73            library,
74            undecoded_gids: RwLock::new(HashSet::new()),
75            cancellation: RwLock::new(CancellationToken::new()),
76            task_counter: TaskCounter::new(),
77        })
78    }
79
80    /// Create a JitController from an in-memory library.
81    pub fn new_from_library(library: crate::jit::JitLibrary, cache_enabled: bool) -> Arc<Self> {
82        let compiler = JitCompiler::new();
83        Arc::new(Self {
84            config: JitControllerConfig {
85                filepath: None,
86                cache_enabled,
87            },
88            compiler,
89            coordinator: RwLock::new(None),
90            type_cache: RwLock::new(TypeCache::new()),
91            next_ctype: AtomicU64::new(1),
92            next_etype: AtomicU64::new(1),
93            terminal_etypes: RwLock::new(HashMap::new()),
94            library,
95            undecoded_gids: RwLock::new(HashSet::new()),
96            cancellation: RwLock::new(CancellationToken::new()),
97            task_counter: TaskCounter::new(),
98        })
99    }
100    pub async fn start(self: &Arc<Self>, client: CoordinatorClient) {
101        {
102            let mut coordinator = self.coordinator.write().await;
103            coordinator.replace(client);
104        }
105        self.load_library(self.library.clone())
106            .await
107            .expect("failed to load initial library at start");
108    }
109
110    /// Load a JIT library: register types with the JIT compiler AND forward
111    /// the underlying `bin` port/gadget types to the coordinator so that
112    /// subsequent `execute` calls can reference them. Used at start-time for
113    /// the initial library and at runtime for dynamically-loaded libraries
114    /// (e.g. from Python). Loading is additive — repeated calls accumulate.
115    pub async fn load_library(self: &Arc<Self>, library: jit::JitLibrary) -> Result<(), tonic::Status> {
116        let _admission = self.cancellation.read().await;
117        let port_types: Vec<_> = library.port_types.iter().filter_map(|pt| pt.base.clone()).collect();
118        let gadget_types: Vec<_> = library.gadget_types.iter().filter_map(|gt| gt.base.clone()).collect();
119
120        self.compiler.load_library(library).await;
121
122        if port_types.is_empty() && gadget_types.is_empty() {
123            return Ok(());
124        }
125        let coordinator_guard = self.coordinator.read().await;
126        let coordinator = coordinator_guard
127            .as_ref()
128            .ok_or_else(|| tonic::Status::failed_precondition("coordinator not connected"))?;
129        let error_model_types = self.register_terminal_types(&gadget_types).await;
130        coordinator
131            .load_library(bin::Library {
132                port_types,
133                gadget_types,
134                error_model_types,
135                ..Default::default()
136            })
137            .await
138    }
139
140    async fn register_terminal_types(&self, gadget_types: &[bin::GadgetType]) -> Vec<bin::ErrorModelType> {
141        let terminal_types = self.compiler.terminal_error_model_types.read().await;
142        let mut terminal_etypes = self.terminal_etypes.write().await;
143        let mut error_model_types = vec![];
144        for gadget in gadget_types {
145            let etype = self.next_etype();
146            let mut terminal_type = terminal_types[&gadget.gtype].as_ref().clone();
147            terminal_type.etype = etype;
148            terminal_etypes.insert(gadget.gtype, etype);
149            error_model_types.push(terminal_type);
150        }
151        error_model_types
152    }
153
154    pub fn next_ctype(&self) -> u64 {
155        self.next_ctype.fetch_add(1, Ordering::SeqCst)
156    }
157
158    pub fn next_etype(&self) -> u64 {
159        self.next_etype.fetch_add(1, Ordering::SeqCst)
160    }
161
162    /// Get cached ctype or allocate and load a new one atomically.
163    /// Holds the lock until the type is loaded to coordinator to prevent races.
164    async fn get_or_load_ctype(&self, check_model_type: &mut bin::CheckModelType, coordinator: &CoordinatorClient) -> u64 {
165        let mut cache = self.type_cache.write().await;
166        if self.config.cache_enabled
167            && let Some(cached) = cache.get_check_model_type(check_model_type)
168        {
169            return cached;
170        }
171        let ctype = self.next_ctype();
172        check_model_type.ctype = ctype;
173        coordinator
174            .load_library(bin::Library {
175                check_model_types: vec![check_model_type.clone()],
176                ..Default::default()
177            })
178            .await
179            .unwrap();
180        if self.config.cache_enabled {
181            cache.insert_check_model_type(check_model_type, ctype);
182        }
183        ctype
184    }
185
186    /// Get cached etype or allocate and load a new one atomically.
187    /// Holds the lock until the type is loaded to coordinator to prevent races.
188    async fn get_or_load_etype(&self, error_model_type: &mut bin::ErrorModelType, coordinator: &CoordinatorClient) -> u64 {
189        let mut cache = self.type_cache.write().await;
190        if self.config.cache_enabled
191            && let Some(cached) = cache.get_error_model_type(error_model_type)
192        {
193            return cached;
194        }
195        let etype = self.next_etype();
196        error_model_type.etype = etype;
197        coordinator
198            .load_library(bin::Library {
199                error_model_types: vec![error_model_type.clone()],
200                ..Default::default()
201            })
202            .await
203            .unwrap();
204        if self.config.cache_enabled {
205            cache.insert_error_model_type(error_model_type, etype);
206        }
207        etype
208    }
209
210    pub async fn clear_cache(&self) {
211        self.type_cache.write().await.clear();
212    }
213
214    /// Execute a JIT instruction, compiling it and sending commands to the coordinator.
215    ///
216    /// Returns the assigned gid for the instantiated gadget once the gadget and check model
217    /// are loaded. The error model is loaded asynchronously in the background to avoid
218    /// circular dependencies (error models depend on future gadgets' gids).
219    pub async fn execute(self: &Arc<Self>, instruction: jit::JitInstruction) -> u64 {
220        let token = self.cancellation.read().await;
221        self.execute_with_token(instruction, token.clone()).await
222    }
223
224    async fn execute_with_token(self: &Arc<Self>, instruction: jit::JitInstruction, token: CancellationToken) -> u64 {
225        let (gadget, mut check_model_type, mut check_model, error_model_future) =
226            Arc::clone(&self.compiler).compile(instruction, token.clone()).await;
227
228        let gid = gadget.gid;
229        if let Some(terminal) = check_model.terminal_error_model.as_mut() {
230            terminal.etype = self.terminal_etypes.read().await[&gadget.gtype];
231        }
232        let cid = gid;
233
234        self.undecoded_gids.write().await.insert(gid);
235
236        {
237            let coordinator_guard = self.coordinator.read().await;
238            let coordinator = coordinator_guard.as_ref().expect("coordinator not connected");
239
240            // NOTE: We assume the coordinator returns the same gid we sent. This assumption
241            // holds for single-node coordinators but may break in distributed decoding systems
242            // where a global id assignment scheme would require the coordinator to return
243            // a different (globally unique) id. In that case, we would need to use the returned
244            // id and update all subsequent references (cid, check_model, error_model, etc.).
245            let returned_gid = coordinator
246                .execute(bin::Instruction {
247                    create: Some(bin::instruction::Create::Gadget(gadget)),
248                })
249                .await
250                .unwrap()
251                .id;
252            assert_eq!(
253                returned_gid, gid,
254                "coordinator returned different gid; distributed id assignment not yet supported"
255            );
256
257            let ctype = self.get_or_load_ctype(&mut check_model_type, coordinator).await;
258
259            let check_model_modifier = build_check_model_modifier(&check_model_type);
260            check_model.ctype = ctype;
261            check_model.modifier = check_model_modifier;
262            coordinator
263                .execute(bin::Instruction {
264                    create: Some(bin::instruction::Create::CheckModel(check_model)),
265                })
266                .await
267                .unwrap();
268        }
269
270        // Spawn error model loading in background. The JIT compiler determines when the
271        // error model future resolves (once output ports are connected), and we send it
272        // to the coordinator as soon as it's ready.
273        let this = Arc::clone(self);
274        let _guard = self.task_counter.guard();
275        tokio::spawn(async move {
276            let _guard = _guard;
277            let (mut error_model_type, error_model) = tokio::select! {
278                result = error_model_future => result,
279                _ = token.cancelled() => { return; }
280            };
281
282            let coordinator_guard = this.coordinator.read().await;
283            let Some(coordinator) = coordinator_guard.as_ref() else {
284                return;
285            };
286
287            let etype = this.get_or_load_etype(&mut error_model_type, coordinator).await;
288
289            let error_model_modifier = build_error_model_modifier(&error_model_type, &error_model);
290            let _ = coordinator
291                .execute(bin::Instruction {
292                    create: Some(bin::instruction::Create::ErrorModel(bin::ErrorModel {
293                        etype,
294                        cid,
295                        tag: error_model.tag.clone(),
296                        modifier: error_model_modifier,
297                        eid: error_model.eid,
298                    })),
299                })
300                .await;
301        });
302
303        gid
304    }
305
306    /// Execute multiple JIT instructions in batch, respecting dependencies between them.
307    ///
308    /// All instructions must specify a non-zero gid. Dependencies (via connectors) are validated:
309    /// referenced gids must either exist in this batch or have been previously executed.
310    /// The entire batch is rejected if any validation fails.
311    ///
312    /// Returns the gids in the same order as the input instructions.
313    ///
314    /// # Errors
315    ///
316    /// Returns `BatchExecuteError` if validation fails.
317    ///
318    /// # Panics
319    ///
320    /// Panics if any spawned task panics during execution.
321    pub async fn batch_execute(
322        self: &Arc<Self>,
323        instructions: Vec<jit::JitInstruction>,
324    ) -> Result<Vec<u64>, BatchExecuteError> {
325        let token = self.cancellation.read().await;
326        let mut batch_gids: HashSet<u64> = HashSet::new();
327        let mut gid_to_index: HashMap<u64, usize> = HashMap::new();
328
329        for (index, instruction) in instructions.iter().enumerate() {
330            let gadget = instruction
331                .gadget
332                .as_ref()
333                .ok_or(BatchExecuteError::MissingGadget { index })?;
334            let gid = gadget.gid;
335            if gid == 0 {
336                return Err(BatchExecuteError::ZeroGid { index });
337            }
338            if batch_gids.contains(&gid) {
339                return Err(BatchExecuteError::DuplicateGid { gid, index });
340            }
341            batch_gids.insert(gid);
342            gid_to_index.insert(gid, index);
343        }
344
345        for (index, instruction) in instructions.iter().enumerate() {
346            let gadget = instruction.gadget.as_ref().unwrap();
347            for connector in &gadget.connectors {
348                let dep_gid = connector.gid;
349                if !batch_gids.contains(&dep_gid) && !self.compiler.contains_gid(dep_gid).await {
350                    return Err(BatchExecuteError::MissingDependency {
351                        index,
352                        gid: gadget.gid,
353                        missing_gid: dep_gid,
354                    });
355                }
356            }
357        }
358
359        let mut dependencies: Vec<Vec<usize>> = vec![Vec::new(); instructions.len()];
360        for (index, instruction) in instructions.iter().enumerate() {
361            let gadget = instruction.gadget.as_ref().unwrap();
362            for connector in &gadget.connectors {
363                let dep_gid = connector.gid;
364                if let Some(&dep_index) = gid_to_index.get(&dep_gid) {
365                    dependencies[index].push(dep_index);
366                }
367            }
368        }
369
370        let gids: Vec<u64> = instructions.iter().map(|i| i.gadget.as_ref().unwrap().gid).collect();
371        let num_instructions = instructions.len();
372        let instructions = Arc::new(instructions);
373        // Use watch channels so that late subscribers still see the completion
374        // signal (broadcast channels drop messages if no subscriber exists yet).
375        let completion_txs: Arc<Vec<_>> =
376            Arc::new((0..num_instructions).map(|_| tokio::sync::watch::channel(false).0).collect());
377
378        let mut handles = Vec::with_capacity(num_instructions);
379        for index in 0..num_instructions {
380            let this = Arc::clone(self);
381            let instructions = Arc::clone(&instructions);
382            let deps = dependencies[index].clone();
383            let completion_txs = Arc::clone(&completion_txs);
384            let token = token.clone();
385            let task_guard = self.task_counter.guard();
386
387            let handle = tokio::spawn(async move {
388                let _task_guard = task_guard;
389                for &dep_index in &deps {
390                    let mut rx = completion_txs[dep_index].subscribe();
391                    tokio::select! {
392                        biased;
393                        () = token.cancelled() => { return None; }
394                        _ = rx.wait_for(|&done| done) => {}
395                    }
396                }
397
398                let instruction = instructions[index].clone();
399                let gid = tokio::select! {
400                    biased;
401                    () = token.cancelled() => { return None; }
402                    gid = this.execute_with_token(instruction, token.clone()) => gid,
403                };
404
405                completion_txs[index].send_replace(true);
406                Some(gid)
407            });
408            handles.push(handle);
409        }
410
411        let results: Vec<u64> = futures_util::future::join_all(handles)
412            .await
413            .into_iter()
414            .map(|r| r.expect("batch execute task panicked"))
415            .collect::<Option<Vec<_>>>()
416            .unwrap_or(gids.clone());
417
418        debug_assert_eq!(results, gids);
419        Ok(gids)
420    }
421
422    /// Decode multiple gadgets concurrently.
423    ///
424    /// All decode operations run in parallel, which is critical for window decoding
425    /// where earlier decodes may depend on later ones. Returns readouts in the same
426    /// order as the input outcomes.
427    ///
428    /// # Errors
429    ///
430    /// Returns `tonic::Status` if any decode operation fails.
431    ///
432    /// # Panics
433    ///
434    /// Panics if any spawned task panics during decoding.
435    pub async fn batch_decode(
436        self: &Arc<Self>,
437        outcomes: Vec<crate::coordinator::Outcomes>,
438    ) -> Result<Vec<crate::coordinator::Readouts>, tonic::Status> {
439        let this = Arc::clone(self);
440        let token = self.cancellation.read().await;
441        let handles: Vec<_> = outcomes
442            .into_iter()
443            .map(|outcome| {
444                let this = Arc::clone(&this);
445                let token = token.clone();
446                let task_guard = self.task_counter.guard();
447                tokio::spawn(async move {
448                    let _task_guard = task_guard;
449                    tokio::select! {
450                        biased;
451                        () = token.cancelled() => None,
452                        result = this.decode_single_with_token(outcome, token.clone()) => Some(result),
453                    }
454                })
455            })
456            .collect();
457
458        let mut results = Vec::with_capacity(handles.len());
459        for r in futures_util::future::join_all(handles).await {
460            match r.expect("batch decode task panicked") {
461                Some(Ok(readouts)) => results.push(readouts),
462                Some(Err(e)) => return Err(e),
463                None => {
464                    return Err(tonic::Status::cancelled("batch decode cancelled by reset"));
465                }
466            }
467        }
468        Ok(results)
469    }
470
471    pub async fn decode_single(
472        self: &Arc<Self>,
473        outcomes: crate::coordinator::Outcomes,
474    ) -> Result<crate::coordinator::Readouts, tonic::Status> {
475        let token = self.cancellation.read().await;
476        self.decode_single_with_token(outcomes, token.clone()).await
477    }
478
479    async fn decode_single_with_token(
480        self: &Arc<Self>,
481        outcomes: crate::coordinator::Outcomes,
482        token: CancellationToken,
483    ) -> Result<crate::coordinator::Readouts, tonic::Status> {
484        let gid = outcomes.gid;
485
486        if !self.undecoded_gids.write().await.remove(&gid) {
487            return Err(tonic::Status::invalid_argument(format!(
488                "decode called for unknown or already-decoded gid: {gid}"
489            )));
490        }
491        let coordinator_guard = self.coordinator.read().await;
492        let coordinator = coordinator_guard
493            .as_ref()
494            .ok_or_else(|| tonic::Status::failed_precondition("coordinator not connected"))?;
495        tokio::select! {
496            biased;
497            () = token.cancelled() => Err(tonic::Status::cancelled(format!(
498                "decode for gid={gid} cancelled by runtime shutdown or reset"
499            ))),
500            result = coordinator.decode(outcomes) => result,
501        }
502    }
503
504    /// Fire the cancellation token to abort any pending error-model loads and
505    /// in-flight decodes. Used by [`crate::server::LocalServer::shutdown`] to
506    /// propagate runtime shutdown into the service layer. Unlike [`Self::reset`],
507    /// this does not wait for tasks to finish, does not refresh the token, and
508    /// does not clear caches — it just signals every cancellable point to bail.
509    pub async fn cancel_pending(&self) {
510        let token = self.cancellation.read().await;
511        token.cancel();
512    }
513
514    pub async fn reset(self: &Arc<Self>, mut flags: crate::coordinator::ResetRequest) -> Result<(), tonic::Status> {
515        // Resetting the library invalidates decoder caches that reference
516        // library-assigned type IDs, so the decoder service must be reset too.
517        if flags.reset_library {
518            flags.reset_decoder_service = true;
519        }
520        // Cancel all pending async tasks, wait for them to finish, then
521        // install a fresh token so post-reset operations proceed normally.
522        {
523            let token = self.cancellation.read().await;
524            token.cancel();
525        }
526        let mut token = self.cancellation.write().await;
527        self.task_counter.wait_for_zero().await;
528        let reset_library = flags.reset_library;
529        if reset_library {
530            self.compiler.reset_library().await;
531            self.terminal_etypes.write().await.clear();
532            self.compiler.load_library(self.library.clone()).await;
533            self.clear_cache().await;
534        } else {
535            self.compiler.reset().await;
536        }
537        self.undecoded_gids.write().await.clear();
538        let coordinator_guard = self.coordinator.read().await;
539        if let Some(coordinator) = coordinator_guard.as_ref() {
540            coordinator.reset(flags).await?;
541
542            // Re-send port types and gadget types so the coordinator stays consistent
543            // with what the JIT controller expects to reference in future compiles.
544            if reset_library {
545                self.next_ctype.store(1, Ordering::SeqCst);
546                self.next_etype.store(1, Ordering::SeqCst);
547                let port_types: Vec<_> = self.library.port_types.iter().map(|pt| pt.base.clone().unwrap()).collect();
548                let gadget_types: Vec<_> = self.library.gadget_types.iter().map(|gt| gt.base.clone().unwrap()).collect();
549                let error_model_types = self.register_terminal_types(&gadget_types).await;
550                coordinator
551                    .load_library(bin::Library {
552                        port_types,
553                        gadget_types,
554                        error_model_types,
555                        ..Default::default()
556                    })
557                    .await
558                    .unwrap();
559            }
560        }
561        *token = CancellationToken::new();
562        Ok(())
563    }
564
565    #[cfg(feature = "cli")]
566    pub fn add_service(self: &Arc<Self>, router: tonic::transport::server::Router) -> tonic::transport::server::Router {
567        let service = jit_controller_server::JitControllerServer::new(JitControllerService(Arc::clone(self)))
568            .max_decoding_message_size(usize::MAX);
569        router.add_service(service)
570    }
571}
572
573#[derive(Debug, Clone)]
574pub enum BatchExecuteError {
575    MissingGadget { index: usize },
576    ZeroGid { index: usize },
577    DuplicateGid { gid: u64, index: usize },
578    MissingDependency { index: usize, gid: u64, missing_gid: u64 },
579}
580
581impl std::fmt::Display for BatchExecuteError {
582    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
583        match self {
584            Self::MissingGadget { index } => {
585                write!(f, "instruction at index {index} has no gadget")
586            }
587            Self::ZeroGid { index } => {
588                write!(
589                    f,
590                    "instruction at index {index} has gid=0; all batch instructions must specify non-zero gid"
591                )
592            }
593            Self::DuplicateGid { gid, index } => {
594                write!(f, "instruction at index {index} has duplicate gid={gid}")
595            }
596            Self::MissingDependency { index, gid, missing_gid } => {
597                write!(
598                    f,
599                    "instruction at index {index} (gid={gid}) depends on gid={missing_gid} which does not exist"
600                )
601            }
602        }
603    }
604}
605
606impl std::error::Error for BatchExecuteError {}
607
608#[cfg(feature = "cli")]
609impl From<BatchExecuteError> for tonic::Status {
610    fn from(err: BatchExecuteError) -> Self {
611        tonic::Status::invalid_argument(err.to_string())
612    }
613}
614
615/// Wrapper that holds Arc<JitController> for implementing the gRPC trait.
616/// This allows gRPC methods to call Arc-based methods like `execute`.
617#[cfg(feature = "cli")]
618struct JitControllerService(Arc<JitController>);
619
620#[cfg(feature = "cli")]
621#[tonic::async_trait]
622impl jit_controller_server::JitController for JitControllerService {
623    async fn load_library(&self, request: tonic::Request<jit::JitLibrary>) -> Result<tonic::Response<()>, tonic::Status> {
624        let library = request.into_inner();
625        self.0.load_library(library).await?;
626        Ok(tonic::Response::new(()))
627    }
628
629    async fn unload(&self, _request: tonic::Request<jit::UnloadJitLibrary>) -> Result<tonic::Response<()>, tonic::Status> {
630        Err(tonic::Status::unimplemented("unload not implemented"))
631    }
632
633    async fn execute(
634        &self,
635        request: tonic::Request<jit::JitInstruction>,
636    ) -> Result<tonic::Response<crate::coordinator::ExecuteResponse>, tonic::Status> {
637        let instruction = request.into_inner();
638        let gid = self.0.execute(instruction).await;
639        Ok(tonic::Response::new(crate::coordinator::ExecuteResponse { id: gid }))
640    }
641
642    async fn batch_execute(
643        &self,
644        request: tonic::Request<BatchExecuteRequest>,
645    ) -> Result<tonic::Response<BatchExecuteResponse>, tonic::Status> {
646        let batch_request = request.into_inner();
647        let gids = self.0.batch_execute(batch_request.instructions).await?;
648        Ok(tonic::Response::new(BatchExecuteResponse { gids }))
649    }
650
651    async fn decode(
652        &self,
653        request: tonic::Request<crate::coordinator::Outcomes>,
654    ) -> Result<tonic::Response<crate::coordinator::Readouts>, tonic::Status> {
655        let readouts = self.0.decode_single(request.into_inner()).await?;
656        Ok(tonic::Response::new(readouts))
657    }
658
659    async fn batch_decode(
660        &self,
661        request: tonic::Request<BatchOutcomes>,
662    ) -> Result<tonic::Response<BatchReadouts>, tonic::Status> {
663        let batch_outcomes = request.into_inner();
664        let readouts = self.0.batch_decode(batch_outcomes.outcomes).await?;
665        Ok(tonic::Response::new(BatchReadouts { readouts }))
666    }
667
668    async fn reset(
669        &self,
670        request: tonic::Request<crate::coordinator::ResetRequest>,
671    ) -> Result<tonic::Response<()>, tonic::Status> {
672        let flags = request.into_inner();
673        self.0.reset(flags).await?;
674        Ok(tonic::Response::new(()))
675    }
676}
677
678/// Build check model modifier that rewrites all remote gadgets with absolute indices.
679/// JIT compiler outputs absolute gid values which must be passed via modifier.
680fn build_check_model_modifier(check_model_type: &bin::CheckModelType) -> Option<check_model::CheckModelModifier> {
681    if check_model_type.remote_gadgets.is_empty() {
682        return None;
683    }
684
685    let reroutes: Vec<_> = check_model_type
686        .remote_gadgets
687        .iter()
688        .enumerate()
689        .map(
690            |(idx, remote_gadget)| check_model::check_model_modifier::RerouteRemoteGadget {
691                remote_gadget_index: idx as u64,
692                value: Some(remote_gadget.clone()),
693            },
694        )
695        .collect();
696
697    Some(check_model::CheckModelModifier {
698        reroute_remote_gadgets: reroutes,
699    })
700}
701
702/// Build error model modifier that rewrites all remote check models with absolute indices
703/// and includes the probability modifier from the error model.
704fn build_error_model_modifier(
705    error_model_type: &bin::ErrorModelType,
706    error_model: &bin::ErrorModel,
707) -> Option<error_model::ErrorModelModifier> {
708    let reroutes: Vec<_> = error_model_type
709        .remote_check_models
710        .iter()
711        .enumerate()
712        .map(
713            |(idx, remote_check_model)| error_model::error_model_modifier::RerouteRemoteCheckModel {
714                remote_check_model_index: idx as u64,
715                value: Some(remote_check_model.clone()),
716            },
717        )
718        .collect();
719
720    let probability_modifier = error_model.modifier.as_ref().and_then(|m| m.probability_modifier.clone());
721
722    let has_reroutes = !reroutes.is_empty();
723    let has_probability = probability_modifier.is_some();
724
725    if !has_reroutes && !has_probability {
726        None
727    } else {
728        Some(error_model::ErrorModelModifier {
729            probability_modifier,
730            reroute_remote_check_models: reroutes,
731        })
732    }
733}
734
735/// Wrapper for CheckModelType that implements Hash/Eq based on structural semantics only.
736/// Excludes: ctype (ID), name, description, and visualization fields (tag, relative).
737#[derive(Clone)]
738pub struct CheckModelTypeKey(pub bin::CheckModelType);
739
740impl PartialEq for CheckModelTypeKey {
741    fn eq(&self, other: &Self) -> bool {
742        let a = &self.0;
743        let b = &other.0;
744        a.gtype == b.gtype
745            && a.checks.len() == b.checks.len()
746            && a.checks.iter().zip(b.checks.iter()).all(|(ca, cb)| checks_eq(ca, cb))
747    }
748}
749
750impl Eq for CheckModelTypeKey {}
751
752impl Hash for CheckModelTypeKey {
753    fn hash<H: Hasher>(&self, state: &mut H) {
754        let cmt = &self.0;
755        cmt.gtype.hash(state);
756        cmt.checks.len().hash(state);
757        for check in &cmt.checks {
758            hash_check(check, state);
759        }
760    }
761}
762
763impl std::fmt::Debug for CheckModelTypeKey {
764    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
765        f.debug_struct("CheckModelTypeKey")
766            .field("gtype", &self.0.gtype)
767            .field("checks_len", &self.0.checks.len())
768            .finish()
769    }
770}
771
772/// Wrapper for ErrorModelType that implements Hash/Eq based on structural semantics only.
773/// Excludes: etype (ID), name, description, and visualization fields (tag, relative).
774#[derive(Clone)]
775pub struct ErrorModelTypeKey(pub bin::ErrorModelType);
776
777impl PartialEq for ErrorModelTypeKey {
778    fn eq(&self, other: &Self) -> bool {
779        let a = &self.0;
780        let b = &other.0;
781        a.ctype == b.ctype
782            && a.errors.len() == b.errors.len()
783            && a.errors.iter().zip(b.errors.iter()).all(|(ea, eb)| errors_eq(ea, eb))
784    }
785}
786
787impl Eq for ErrorModelTypeKey {}
788
789impl Hash for ErrorModelTypeKey {
790    fn hash<H: Hasher>(&self, state: &mut H) {
791        hash_error_model_type_structural(&self.0, state);
792    }
793}
794
795/// Structural hash for [`bin::ErrorModelType`] — the same fields hashed by
796/// [`ErrorModelTypeKey::hash`], exposed as a free function so callers can
797/// fingerprint a borrowed `ErrorModelType` without constructing (and cloning
798/// into) an [`ErrorModelTypeKey`].
799///
800/// Used by `coordinator::decoder_cache_key::etype_digest` to fold the resolved
801/// error-model-type structure (including the full `errors` list) into the
802/// `loaded_decoders` cache key.
803pub(crate) fn hash_error_model_type_structural<H: Hasher>(emt: &bin::ErrorModelType, state: &mut H) {
804    emt.ctype.hash(state);
805    emt.errors.len().hash(state);
806    for error in &emt.errors {
807        hash_error(error, state);
808    }
809}
810
811impl std::fmt::Debug for ErrorModelTypeKey {
812    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
813        f.debug_struct("ErrorModelTypeKey")
814            .field("ctype", &self.0.ctype)
815            .field("errors_len", &self.0.errors.len())
816            .finish()
817    }
818}
819
820fn checks_eq(a: &check_model_type::Check, b: &check_model_type::Check) -> bool {
821    a.measurements == b.measurements && a.naturally_flipped == b.naturally_flipped
822}
823
824fn hash_check<H: Hasher>(check: &check_model_type::Check, state: &mut H) {
825    check.measurements.hash(state);
826    check.naturally_flipped.hash(state);
827}
828
829fn errors_eq(a: &error_model_type::Error, b: &error_model_type::Error) -> bool {
830    a.checks == b.checks
831        && a.residual == b.residual
832        && a.readout_flips == b.readout_flips
833        && a.probability.to_bits() == b.probability.to_bits()
834}
835
836fn hash_error<H: Hasher>(error: &error_model_type::Error, state: &mut H) {
837    error.checks.hash(state);
838    error.residual.hash(state);
839    error.readout_flips.hash(state);
840    error.probability.to_bits().hash(state);
841}
842
843/// Cache for reusing CheckModelType and ErrorModelType across JIT compilations.
844#[derive(Default)]
845pub struct TypeCache {
846    check_model_types: HashMap<CheckModelTypeKey, u64>,
847    error_model_types: HashMap<ErrorModelTypeKey, u64>,
848}
849
850impl TypeCache {
851    pub fn new() -> Self {
852        Self::default()
853    }
854
855    pub fn get_check_model_type(&self, check_model_type: &bin::CheckModelType) -> Option<u64> {
856        let key = CheckModelTypeKey(check_model_type.clone());
857        self.check_model_types.get(&key).copied()
858    }
859
860    pub fn insert_check_model_type(&mut self, check_model_type: &bin::CheckModelType, ctype: u64) {
861        let key = CheckModelTypeKey(check_model_type.clone());
862        self.check_model_types.insert(key, ctype);
863    }
864
865    pub fn get_error_model_type(&self, error_model_type: &bin::ErrorModelType) -> Option<u64> {
866        let key = ErrorModelTypeKey(error_model_type.clone());
867        self.error_model_types.get(&key).copied()
868    }
869
870    pub fn insert_error_model_type(&mut self, error_model_type: &bin::ErrorModelType, etype: u64) {
871        let key = ErrorModelTypeKey(error_model_type.clone());
872        self.error_model_types.insert(key, etype);
873    }
874
875    pub fn clear(&mut self) {
876        self.check_model_types.clear();
877        self.error_model_types.clear();
878    }
879}