Skip to main content

deq_runtime/jit/
jit_compiler.rs

1use crate::misc::index::FUTURE_CHECK_CID;
2use crate::{bin, jit};
3use hashbrown::{HashMap, HashSet};
4use std::sync::Arc;
5use std::sync::atomic::{AtomicU64, Ordering};
6use tokio::sync::{RwLock, watch};
7use tokio_util::sync::CancellationToken;
8
9type InputVirtualCheckMap = Vec<Vec<jit::jit_gadget_type::Error>>;
10
11fn input_virtual_check_map(
12    gadget_type: &jit::JitGadgetType,
13    port_types: &HashMap<u64, Arc<jit::JitPortType>>,
14) -> Arc<InputVirtualCheckMap> {
15    let mut input_map: InputVirtualCheckMap = gadget_type
16        .base
17        .as_ref()
18        .unwrap()
19        .inputs
20        .iter()
21        .map(|port| vec![jit::jit_gadget_type::Error::default(); port_types[&port.ptype].stabilizers.len()])
22        .collect();
23    for (finished, checks) in [(true, &gadget_type.finished_checks), (false, &gadget_type.unfinished_checks)] {
24        for (index, check) in checks.iter().enumerate() {
25            for measurement in &check.measurements {
26                if let Some(port) = measurement.input_port {
27                    let port = usize::try_from(port).expect("input port index exceeds usize");
28                    let measurement_index =
29                        usize::try_from(measurement.measurement_index).expect("input check index exceeds usize");
30                    let entry = &mut input_map[port][measurement_index];
31                    if finished {
32                        entry.finished_checks.push(index as u64);
33                    } else {
34                        entry.unfinished_checks.push(index as u64);
35                    }
36                }
37            }
38        }
39    }
40    Arc::new(input_map)
41}
42
43pub struct JitCompiler {
44    pub jit_port_types: RwLock<HashMap<u64, Arc<jit::JitPortType>>>,
45    pub jit_gadget_types: RwLock<HashMap<u64, Arc<jit::JitGadgetType>>>,
46    pub terminal_error_model_types: RwLock<HashMap<u64, Arc<bin::ErrorModelType>>>,
47    input_virtual_check_maps: RwLock<HashMap<u64, Arc<InputVirtualCheckMap>>>,
48    pub current_gid: AtomicU64,
49    pub gadgets: RwLock<HashMap<u64, JitGadgetState>>,
50}
51
52pub struct JitGadgetState {
53    pub gtype: u64,
54    pub outputs: Vec<watch::Sender<Option<bin::gadget::Connector>>>,
55    /// The expanded output checks for each output port - each check is a set of explicit measurements
56    /// paired with the accumulated naturally_flipped parity (affine constant)
57    output_checks: Vec<Vec<(HashSet<ExplicitMeasurement>, bool)>>,
58    /// build the reverse mapping from input virtual checks to all the finished and unfinished
59    /// checks that includes the input virtual check; it has the same type as jit_gadget_type::Error
60    /// but doesn't have the base bin::Error information
61    pub input_virtual_check_map: Arc<Vec<Vec<jit::jit_gadget_type::Error>>>,
62    /// for each gadget, we need to resolve the output virtual checks into concrete checks
63    /// indexed by explicit cid and check index
64    output_virtual_checks: watch::Sender<Option<Arc<Vec<HashSet<ExplicitCheck>>>>>,
65}
66
67/// An explicit measurement with absolute gid instead of remote_gadget index
68#[derive(Eq, PartialEq, Hash, Clone, Debug)]
69struct ExplicitMeasurement {
70    gid: u64,
71    measurement_index: u64,
72}
73
74#[derive(Eq, PartialEq, Hash, Clone, Debug)]
75struct ExplicitCheck {
76    // in the JIT compiler, cid is always equal to gid for simplicity
77    cid: u64,
78    check_index: u64,
79}
80
81impl JitCompiler {
82    pub fn new() -> Arc<Self> {
83        Arc::new(Self {
84            jit_port_types: RwLock::new(HashMap::new()),
85            jit_gadget_types: RwLock::new(HashMap::new()),
86            terminal_error_model_types: RwLock::new(HashMap::new()),
87            input_virtual_check_maps: RwLock::new(HashMap::new()),
88            gadgets: RwLock::new(HashMap::new()),
89            current_gid: AtomicU64::new(1),
90        })
91    }
92
93    /// it is unsafe to call reset while some other async operations are ongoing
94    pub async fn reset(&self) {
95        let mut gadgets = self.gadgets.write().await;
96        self.current_gid.store(1, Ordering::SeqCst);
97        gadgets.clear();
98    }
99
100    /// Clear registered types and compiled gadgets after all ongoing operations have stopped.
101    pub async fn reset_library(&self) {
102        self.reset().await;
103        self.jit_port_types.write().await.clear();
104        self.jit_gadget_types.write().await.clear();
105        self.terminal_error_model_types.write().await.clear();
106        self.input_virtual_check_maps.write().await.clear();
107    }
108
109    pub async fn contains_gid(&self, gid: u64) -> bool {
110        self.gadgets.read().await.contains_key(&gid)
111    }
112
113    async fn get_output_connector(
114        &self,
115        gid: u64,
116        port_index: usize,
117        token: CancellationToken,
118    ) -> Option<bin::gadget::Connector> {
119        let mut receiver = {
120            let gadgets = self.gadgets.read().await;
121            let sender = &gadgets[&gid].outputs[port_index];
122            if let Some(value) = *sender.borrow() {
123                return Some(value);
124            }
125            sender.subscribe()
126        };
127        tokio::select! {
128            result = receiver.wait_for(Option::is_some) => result.ok().and_then(|value| *value),
129            () = token.cancelled() => None,
130        }
131    }
132
133    async fn get_input_virtual_check_map(&self, gid: u64) -> Arc<Vec<Vec<jit::jit_gadget_type::Error>>> {
134        let gadgets = self.gadgets.read().await;
135        gadgets[&gid].input_virtual_check_map.clone()
136    }
137
138    async fn get_output_virtual_checks(
139        &self,
140        gid: u64,
141        token: CancellationToken,
142    ) -> Option<Arc<Vec<HashSet<ExplicitCheck>>>> {
143        let mut receiver = {
144            let gadgets = self.gadgets.read().await;
145            let sender = &gadgets[&gid].output_virtual_checks;
146            if let Some(value) = sender.borrow().as_ref() {
147                return Some(Arc::clone(value));
148            }
149            sender.subscribe()
150        };
151        tokio::select! {
152            result = receiver.wait_for(Option::is_some) => result.ok().and_then(|value| value.clone()),
153            () = token.cancelled() => None,
154        }
155    }
156
157    async fn publish_output_virtual_checks(&self, gid: u64, checks: Arc<Vec<HashSet<ExplicitCheck>>>) {
158        let gadgets = self.gadgets.read().await;
159        gadgets[&gid].output_virtual_checks.send_replace(Some(checks));
160    }
161
162    pub async fn load_library(&self, library: jit::JitLibrary) {
163        let mut jit_port_types = self.jit_port_types.write().await;
164        let mut jit_gadget_types = self.jit_gadget_types.write().await;
165        let mut terminal_types = self.terminal_error_model_types.write().await;
166        let mut input_maps = self.input_virtual_check_maps.write().await;
167        for port_type in library.port_types {
168            let ptype = port_type.base.as_ref().unwrap().ptype;
169            assert!(!jit_port_types.contains_key(&ptype));
170            jit_port_types.insert(ptype, Arc::new(port_type));
171        }
172        for gadget_type in library.gadget_types {
173            let gtype = gadget_type.base.as_ref().unwrap().gtype;
174            assert!(!jit_gadget_types.contains_key(&gtype));
175            if gadget_type
176                .base
177                .as_ref()
178                .unwrap()
179                .inputs
180                .iter()
181                .all(|port| jit_port_types.contains_key(&port.ptype))
182            {
183                input_maps.insert(gtype, input_virtual_check_map(&gadget_type, &jit_port_types));
184            }
185            let mut terminal_type = bin::ErrorModelType {
186                etype: gtype,
187                ..Default::default()
188            };
189            for error in &gadget_type.errors {
190                let mut terminal_error = error.base.clone().unwrap();
191                terminal_error.checks.extend(error.finished_checks.iter().map(|&check_index| {
192                    bin::error_model_type::RemoteCheck {
193                        remote_check_model: None,
194                        check_index,
195                    }
196                }));
197                if !error.unfinished_checks.is_empty() {
198                    if terminal_type.remote_check_models.is_empty() {
199                        terminal_type
200                            .remote_check_models
201                            .push(bin::error_model_type::RemoteCheckModel {
202                                absolute_cid: Some(FUTURE_CHECK_CID),
203                                ..Default::default()
204                            });
205                    }
206                    terminal_error.checks.push(bin::error_model_type::RemoteCheck {
207                        remote_check_model: Some(0),
208                        check_index: 0,
209                    });
210                }
211                terminal_type.errors.push(terminal_error);
212            }
213            terminal_types.insert(gtype, Arc::new(terminal_type));
214            jit_gadget_types.insert(gtype, Arc::new(gadget_type));
215        }
216        drop(jit_gadget_types);
217    }
218
219    pub async fn compile(
220        self: &Arc<Self>,
221        mut instruction: jit::JitInstruction,
222        token: CancellationToken,
223    ) -> (
224        bin::Gadget,
225        bin::CheckModelType,
226        bin::CheckModel,
227        // error model comes later asynchronously because it needs to wait for all errors to be
228        // expanded into appropriate checks
229        impl Future<Output = (bin::ErrorModelType, bin::ErrorModel)> + Send + use<>,
230    ) {
231        let jit_port_types = self.jit_port_types.read().await;
232        let jit_gadget_types = self.jit_gadget_types.read().await;
233        let mut gadgets = self.gadgets.write().await;
234        let mut gadget = instruction.gadget.take().unwrap();
235        let gid = if gadget.gid != 0 {
236            // User-provided gid: advance current_gid past it to avoid conflicts
237            self.current_gid.fetch_max(gadget.gid + 1, Ordering::SeqCst);
238            gadget.gid
239        } else {
240            let gid = self.current_gid.fetch_add(1, Ordering::SeqCst);
241            gadget.gid = gid;
242            gid
243        };
244        let probability_modifier = instruction.probability_modifier.take();
245        let gtype = gadget.gtype;
246        let jit_gadget_type = jit_gadget_types
247            .get(&gtype)
248            .unwrap_or_else(|| panic!("Gadget type not found: {}", gtype))
249            .clone();
250        let gadget_type = jit_gadget_type.base.as_ref().unwrap();
251        // Collect the output checks from each input port's input gadget
252        let mut input_checks: Vec<Vec<(HashSet<ExplicitMeasurement>, bool)>> = vec![];
253        let cached_input_map = self.input_virtual_check_maps.read().await.get(&gtype).cloned();
254        let input_virtual_check_map = if let Some(map) = cached_input_map {
255            map
256        } else {
257            let map = input_virtual_check_map(&jit_gadget_type, &jit_port_types);
258            self.input_virtual_check_maps.write().await.insert(gtype, Arc::clone(&map));
259            map
260        };
261        for (input_port_index, connector) in gadget.connectors.iter().enumerate() {
262            debug_assert!(gadgets.contains_key(&connector.gid));
263            debug_assert!({
264                let peer_outputs = &gadgets[&connector.gid].outputs;
265                (connector.port as usize) < peer_outputs.len() && peer_outputs[connector.port as usize].borrow().is_none()
266            });
267            let input_gadget = gadgets.get_mut(&connector.gid).unwrap();
268            input_gadget.outputs[connector.port as usize].send_replace(Some(bin::gadget::Connector {
269                gid,
270                port: input_port_index as u64,
271            }));
272            // Take the output checks from this port of the input gadget
273            let peer_output_checks = std::mem::take(&mut input_gadget.output_checks[connector.port as usize]);
274            debug_assert_eq!(input_virtual_check_map[input_port_index].len(), peer_output_checks.len());
275            input_checks.push(peer_output_checks);
276        }
277        // expand internal checks and add them to the generated check model
278        let mut remote_gadget_sequencer = RemoteGadgetSequencer::new();
279        let mut check_model_type = bin::CheckModelType {
280            ctype: gid, // need to create a new check model every time
281            gtype,
282            ..Default::default()
283        };
284        for check in &jit_gadget_type.finished_checks {
285            let (measurements, naturally_flipped) = expand_check_measurements(check, &input_checks, gid);
286            check_model_type
287                .checks
288                .push(remote_gadget_sequencer.measurements_to_bin_check(
289                    check,
290                    &measurements,
291                    naturally_flipped,
292                    gid,
293                    &gadgets,
294                ));
295        }
296        // Build the output_checks for this gadget - each port has a list of expanded measurement sets
297        let mut output_checks = vec![];
298        let mut output_check_index = 0;
299        for port in gadget_type.outputs.iter() {
300            let port_type = jit_port_types.get(&port.ptype).unwrap();
301            let mut port_checks = vec![];
302            for _ in 0..port_type.stabilizers.len() {
303                let check = &jit_gadget_type.unfinished_checks[output_check_index];
304                let expanded = expand_check_measurements(check, &input_checks, gid);
305                port_checks.push(expanded);
306                output_check_index += 1;
307            }
308            output_checks.push(port_checks);
309        }
310        debug_assert!(output_check_index == jit_gadget_type.unfinished_checks.len());
311        // Finalize checks by subtracting measurement bias from remote measurements
312        remote_gadget_sequencer.apply_bias_to_check_model(&mut check_model_type);
313        // Assign the sequenced remote_gadgets to the check_model_type
314        check_model_type.remote_gadgets = remote_gadget_sequencer.finalize();
315        let gadget_state = JitGadgetState {
316            gtype,
317            outputs: gadget_type.outputs.iter().map(|_| watch::channel(None).0).collect(),
318            output_checks,
319            input_virtual_check_map,
320            output_virtual_checks: watch::channel(None).0,
321        };
322        gadgets.insert(gid, gadget_state);
323        let check_model = bin::CheckModel {
324            gid,
325            ctype: gid, // need to create a new check model every time
326            cid: gid,
327            terminal_error_model: Some(bin::ErrorModel {
328                etype: gtype,
329                cid: gid,
330                eid: gid,
331                modifier: probability_modifier
332                    .clone()
333                    .map(|modifier| bin::error_model::ErrorModelModifier {
334                        probability_modifier: Some(modifier),
335                        ..Default::default()
336                    }),
337                ..Default::default()
338            }),
339            ..Default::default()
340        };
341        drop(jit_port_types);
342        drop(jit_gadget_types);
343        drop(gadgets);
344        let this = Arc::clone(self);
345        (gadget, check_model_type, check_model, async move {
346            // to avoid infinite dependency chain to the final measurement gadget, we need to achieve this property:
347            // if a gadget's unfinished checks do not ever refer to the gadget's input checks, then it can immediately
348            // resolve its first-stage check state
349            let mut output_virtual_checks = Vec::with_capacity(jit_gadget_type.unfinished_checks.len());
350            let mut cancelled = false;
351            for port_index in 0..jit_gadget_type.base.as_ref().unwrap().outputs.len() {
352                // wait for the output port to be connected; otherwise we won't be able to resolve the checks
353                let connector = this.get_output_connector(gid, port_index, token.clone()).await;
354                let Some(connector) = connector else {
355                    cancelled = true;
356                    break;
357                };
358                let peer_input_check_map = this.get_input_virtual_check_map(connector.gid).await;
359                let peer_input_checks = &peer_input_check_map[connector.port as usize];
360                // iterate over all the output virtual checks on this port and resolve them using
361                // the resolved information from the peer gadget
362                let mut peer_output_virtual_checks: Option<Arc<Vec<HashSet<ExplicitCheck>>>> = None;
363                for check in peer_input_checks.iter() {
364                    // expanding the virtual check into explicit checks
365                    let mut explicit_checks = HashSet::<ExplicitCheck>::new();
366                    for &check_index in check.finished_checks.iter() {
367                        let explicit_check = ExplicitCheck {
368                            cid: connector.gid,
369                            check_index,
370                        };
371                        debug_assert!(!explicit_checks.contains(&explicit_check));
372                        explicit_checks.insert(explicit_check);
373                    }
374                    // if there exists any unfinished checks, we must wait for the peer's output virtual checks
375                    // to be resolved first (it is done in the peer's own error resolving Future function)
376                    // note that this is rarely happening
377                    if !check.unfinished_checks.is_empty() {
378                        if peer_output_virtual_checks.is_none() {
379                            peer_output_virtual_checks = this.get_output_virtual_checks(connector.gid, token.clone()).await;
380                        }
381                        let Some(peer_output_virtual_checks_arc) = peer_output_virtual_checks.as_ref() else {
382                            cancelled = true;
383                            break;
384                        };
385                        for &check_index in check.unfinished_checks.iter() {
386                            let peer_explicit_checks = &peer_output_virtual_checks_arc[check_index as usize];
387                            for check in peer_explicit_checks {
388                                if !explicit_checks.remove(check) {
389                                    explicit_checks.insert(check.clone());
390                                }
391                            }
392                        }
393                    }
394                    output_virtual_checks.push(explicit_checks);
395                }
396                if cancelled {
397                    break;
398                }
399            }
400            // If cancelled, return a dummy error model. The caller (JitController)
401            // wraps this future in select! against the token, so the result is
402            // discarded. We must NOT publish partial output_virtual_checks because
403            // other in-flight futures could read them and panic on bad indices.
404            if cancelled {
405                return (bin::ErrorModelType::default(), bin::ErrorModel::default());
406            }
407            let output_virtual_checks = Arc::new(output_virtual_checks);
408            debug_assert!(output_virtual_checks.len() == jit_gadget_type.unfinished_checks.len());
409            // once the output virtual checks are resolved, we can update the state so that
410            // the previous gadgets depending on this gadget can proceed
411            this.publish_output_virtual_checks(gid, output_virtual_checks.clone()).await;
412            // after we have prepared the data for the previous gadgets to consume, we then focus on myself generating
413            // errors and also the remote check model entries as necessary; we build the remote check models in a way
414            // that maximizes the probability of error model reusing: we iterate over errors and for each check that it
415            // refers to, we build the remote check model entry. This means that regardless of how many hops it takes to
416            // reach the target check, the error's relative check indices remain unchanged, thus they can be reused easily
417            let mut remote_check_model_sequencer = RemoteCheckModelSequencer::new();
418            // For each error, expand unfinished checks using symmetric difference (XOR)
419            let mut errors = Vec::with_capacity(jit_gadget_type.errors.len());
420            for jit_error in jit_gadget_type.errors.iter() {
421                if jit_error.unfinished_checks.is_empty() {
422                    // Fast path: only finished checks — all local, no HashSet needed
423                    errors.push(remote_check_model_sequencer.finished_only_to_bin_error(jit_error));
424                } else {
425                    let explicit_checks = expand_error_checks(jit_error, &output_virtual_checks, gid);
426                    errors.push(remote_check_model_sequencer.explicit_checks_to_bin_error(jit_error, &explicit_checks, gid));
427                }
428            }
429            // Apply bias to all errors
430            remote_check_model_sequencer.apply_bias_to_errors(&mut errors);
431            let remote_check_models = remote_check_model_sequencer.finalize();
432            // now construct the error model
433            let error_model_type = bin::ErrorModelType {
434                etype: gid, // need to create a new error model every time
435                ctype: crate::misc::index::WILDCARD,
436                remote_check_models,
437                errors,
438                ..Default::default()
439            };
440            let error_model = bin::ErrorModel {
441                cid: gid,
442                etype: gid,
443                eid: gid,
444                modifier: probability_modifier.map(|pm| bin::error_model::ErrorModelModifier {
445                    probability_modifier: Some(pm),
446                    reroute_remote_check_models: vec![],
447                }),
448                ..Default::default()
449            };
450            (error_model_type, error_model)
451        })
452    }
453}
454
455/// Helper struct to sequence remote gadgets across multiple checks
456struct RemoteGadgetSequencer {
457    gid_to_remote_index: HashMap<u64, u64>,
458    remote_gadgets: Vec<bin::check_model_type::RemoteGadget>,
459    minimum_measurement_indices: Vec<u64>,
460}
461
462impl RemoteGadgetSequencer {
463    fn new() -> Self {
464        Self {
465            gid_to_remote_index: HashMap::new(),
466            remote_gadgets: vec![],
467            minimum_measurement_indices: vec![],
468        }
469    }
470
471    fn get_or_insert(&mut self, gid: u64, gtype: u64, measurement_index: u64) -> u64 {
472        if let Some(&index) = self.gid_to_remote_index.get(&gid) {
473            self.minimum_measurement_indices[index as usize] =
474                std::cmp::min(self.minimum_measurement_indices[index as usize], measurement_index);
475            index
476        } else {
477            let index = self.remote_gadgets.len() as u64;
478            self.gid_to_remote_index.insert(gid, index);
479            self.remote_gadgets.push(bin::check_model_type::RemoteGadget {
480                absolute_gid: Some(gid),
481                expecting_gtype: gtype,
482                ..Default::default()
483            });
484            self.minimum_measurement_indices.push(measurement_index);
485            index
486        }
487    }
488
489    fn get_measurement_bias(&self, remote_index: u64) -> u64 {
490        self.minimum_measurement_indices[remote_index as usize]
491    }
492
493    /// Convert a set of explicit measurements to a bin::check_model_type::Check
494    fn measurements_to_bin_check(
495        &mut self,
496        jit_check: &jit::jit_gadget_type::Check,
497        measurements: &HashSet<ExplicitMeasurement>,
498        naturally_flipped: bool,
499        current_gid: u64,
500        gadgets: &HashMap<u64, JitGadgetState>,
501    ) -> bin::check_model_type::Check {
502        let mut check = jit_check.base.as_ref().unwrap().clone();
503        check.naturally_flipped = naturally_flipped;
504        debug_assert!(check.measurements.is_empty());
505        for measurement in measurements.iter() {
506            let (remote_gadget, measurement_index) = if measurement.gid != current_gid {
507                let remote_gtype = gadgets[&measurement.gid].gtype;
508                let remote_index = self.get_or_insert(measurement.gid, remote_gtype, measurement.measurement_index);
509                (Some(remote_index), measurement.measurement_index)
510            } else {
511                (None, measurement.measurement_index)
512            };
513            check.measurements.push(bin::check_model_type::RemoteMeasurement {
514                remote_gadget,
515                measurement_index,
516            });
517        }
518        // Sort measurements for deterministic ordering (HashSet iteration is
519        // non-deterministic). This is critical for type cache hits across shots.
520        check.measurements.sort_by(|a, b| {
521            a.remote_gadget
522                .cmp(&b.remote_gadget)
523                .then(a.measurement_index.cmp(&b.measurement_index))
524        });
525        check
526    }
527
528    /// Finalize checks by subtracting measurement bias from remote measurements
529    fn apply_bias_to_check_model(&self, check_model_type: &mut bin::CheckModelType) {
530        for check in check_model_type.checks.iter_mut() {
531            for measurement in check.measurements.iter_mut() {
532                if let Some(remote_index) = measurement.remote_gadget {
533                    measurement.measurement_index -= self.get_measurement_bias(remote_index);
534                }
535            }
536        }
537    }
538
539    fn finalize(mut self) -> Vec<bin::check_model_type::RemoteGadget> {
540        for (index, remote_gadget) in self.remote_gadgets.iter_mut().enumerate() {
541            remote_gadget.measurement_bias = self.minimum_measurement_indices[index];
542        }
543        self.remote_gadgets
544    }
545}
546
547/// Helper struct to sequence remote check models across multiple errors
548struct RemoteCheckModelSequencer {
549    cid_to_remote_index: HashMap<u64, u64>,
550    remote_check_models: Vec<bin::error_model_type::RemoteCheckModel>,
551    minimum_check_indices: Vec<u64>,
552}
553
554impl RemoteCheckModelSequencer {
555    fn new() -> Self {
556        Self {
557            cid_to_remote_index: HashMap::new(),
558            remote_check_models: vec![],
559            minimum_check_indices: vec![],
560        }
561    }
562
563    fn get_or_insert(&mut self, cid: u64, check_index: u64) -> u64 {
564        if let Some(&index) = self.cid_to_remote_index.get(&cid) {
565            self.minimum_check_indices[index as usize] =
566                std::cmp::min(self.minimum_check_indices[index as usize], check_index);
567            index
568        } else {
569            let index = self.remote_check_models.len() as u64;
570            self.cid_to_remote_index.insert(cid, index);
571            self.remote_check_models.push(bin::error_model_type::RemoteCheckModel {
572                expecting_ctype: cid,
573                absolute_cid: Some(cid),
574                ..Default::default()
575            });
576            self.minimum_check_indices.push(check_index);
577            index
578        }
579    }
580
581    fn get_check_bias(&self, remote_index: u64) -> u64 {
582        self.minimum_check_indices[remote_index as usize]
583    }
584
585    /// Fast path for errors that only reference finished checks (no unfinished checks).
586    /// All finished checks are local (cid = current_gid, remote_check_model = None),
587    /// so we skip HashSet construction, hashing, and sorting entirely.
588    fn finished_only_to_bin_error(&mut self, jit_error: &jit::jit_gadget_type::Error) -> bin::error_model_type::Error {
589        debug_assert!(jit_error.unfinished_checks.is_empty());
590        let mut error = jit_error.base.clone().unwrap();
591        // Finished checks are already sorted by index in the JIT representation,
592        // and all are local (no remote_check_model), so no sorting needed.
593        for &check_index in jit_error.finished_checks.iter() {
594            error.checks.push(bin::error_model_type::RemoteCheck {
595                remote_check_model: None,
596                check_index,
597            });
598        }
599        error
600    }
601
602    /// Convert a set of explicit checks to a bin::error_model_type::Error
603    fn explicit_checks_to_bin_error(
604        &mut self,
605        jit_error: &jit::jit_gadget_type::Error,
606        explicit_checks: &HashSet<ExplicitCheck>,
607        current_gid: u64,
608    ) -> bin::error_model_type::Error {
609        let mut error = jit_error.base.clone().unwrap();
610        for explicit_check in explicit_checks.iter() {
611            let cid = explicit_check.cid;
612            let remote_check_model = if cid == current_gid {
613                None
614            } else {
615                Some(self.get_or_insert(cid, explicit_check.check_index))
616            };
617            error.checks.push(bin::error_model_type::RemoteCheck {
618                remote_check_model,
619                check_index: explicit_check.check_index,
620            });
621        }
622        // Sort checks for deterministic ordering (HashSet iteration is
623        // non-deterministic). This is critical for type cache hits across shots.
624        error.checks.sort_by(|a, b| {
625            a.remote_check_model
626                .cmp(&b.remote_check_model)
627                .then(a.check_index.cmp(&b.check_index))
628        });
629        error
630    }
631
632    /// Apply bias to all errors by subtracting the minimum check index
633    fn apply_bias_to_errors(&self, errors: &mut [bin::error_model_type::Error]) {
634        for error in errors.iter_mut() {
635            for remote_check in error.checks.iter_mut() {
636                remote_check.check_index -= match remote_check.remote_check_model {
637                    Some(remote_index) => self.get_check_bias(remote_index),
638                    None => 0,
639                };
640            }
641        }
642    }
643
644    fn finalize(mut self) -> Vec<bin::error_model_type::RemoteCheckModel> {
645        for (index, remote_check_model) in self.remote_check_models.iter_mut().enumerate() {
646            remote_check_model.check_bias = self.minimum_check_indices[index];
647        }
648        self.remote_check_models
649    }
650}
651
652/// Expand a JIT check into a set of explicit measurements by expanding references to input port measurements.
653/// Returns the measurement set and the accumulated `naturally_flipped` parity (affine constant).
654fn expand_check_measurements(
655    check: &jit::jit_gadget_type::Check,
656    input_checks: &[Vec<(HashSet<ExplicitMeasurement>, bool)>],
657    gid: u64,
658) -> (HashSet<ExplicitMeasurement>, bool) {
659    let mut naturally_flipped = check.base.as_ref().unwrap().naturally_flipped;
660    let mut measurement_set = HashSet::<ExplicitMeasurement>::new();
661    for measurement in check.measurements.iter() {
662        if let Some(input_port) = measurement.input_port {
663            let input_port_idx = input_port as usize;
664            let measurement_idx = measurement.measurement_index as usize;
665            assert!(
666                input_port_idx < input_checks.len() && measurement_idx < input_checks[input_port_idx].len(),
667                "malformed JitLibrary: check measurement references input port {input_port} \
668                 measurement {measurement_idx}, but input port has {} expanded checks \
669                 (this typically means a COMPOSE bound the same wire to multiple INPUT or \
670                 OUTPUT ports, or that two connectors share the same source (gid, port))",
671                input_checks.get(input_port_idx).map_or(0, std::vec::Vec::len),
672            );
673            let (input_measurements, input_flipped) = &input_checks[input_port_idx][measurement_idx];
674            naturally_flipped ^= input_flipped;
675            for input_measurement in input_measurements.iter() {
676                if !measurement_set.remove(input_measurement) {
677                    measurement_set.insert(input_measurement.clone());
678                }
679            }
680        } else {
681            let explicit_measurement = ExplicitMeasurement {
682                gid,
683                measurement_index: measurement.measurement_index,
684            };
685            if !measurement_set.remove(&explicit_measurement) {
686                measurement_set.insert(explicit_measurement);
687            }
688        }
689    }
690    (measurement_set, naturally_flipped)
691}
692
693/// Expand a JIT error into a set of explicit checks by expanding references to unfinished checks
694fn expand_error_checks(
695    jit_error: &jit::jit_gadget_type::Error,
696    output_virtual_checks: &[HashSet<ExplicitCheck>],
697    gid: u64,
698) -> HashSet<ExplicitCheck> {
699    let mut check_set = HashSet::<ExplicitCheck>::new();
700    // Start with finished checks (local to this gadget)
701    for &check_index in jit_error.finished_checks.iter() {
702        let explicit_check = ExplicitCheck { cid: gid, check_index };
703        if !check_set.remove(&explicit_check) {
704            check_set.insert(explicit_check);
705        }
706    }
707    // XOR (symmetric difference) with each unfinished check's resolved checks
708    for &check_index in jit_error.unfinished_checks.iter() {
709        let resolved_checks = &output_virtual_checks[check_index as usize];
710        for resolved_check in resolved_checks.iter() {
711            if !check_set.remove(resolved_check) {
712                check_set.insert(resolved_check.clone());
713            }
714        }
715    }
716    check_set
717}