Skip to main content

faultscope_core/
decoder.rs

1use std::collections::{HashMap, HashSet};
2use std::ffi::c_void;
3use std::os::raw::c_char;
4use std::sync::Arc;
5
6use crate::{GraphlikeDecodingProblem, Mask, NpError, NpResult};
7
8pub const NATIVE_DECODER_PLUGIN_ABI_VERSION: u32 = 4;
9pub const NATIVE_DECODER_PLUGIN_ABI_NAME: &str = "faultscope.native_decoder_plugin.v4";
10pub const NATIVE_DECODER_PLUGIN_CAPSULE_NAME: &str = "faultscope.native_decoder_plugin.v4";
11pub const NATIVE_DECODER_PLUGIN_CAPSULE_METHOD: &str = "__faultscope_native_decoder_capsule__";
12pub const NATIVE_DECODER_PLUGIN_ENTRY_POINT_GROUP: &str = "faultscope.native_decoders";
13pub const NATIVE_DECODER_FACTORY_FLAG_THREAD_SAFE: u64 = 1 << 0;
14pub const NATIVE_DECODER_PLUGIN_STATUS_OK: i32 = 0;
15pub const NATIVE_DECODER_PLUGIN_STATUS_ERROR: i32 = 1;
16pub const NATIVE_DECODER_BATCH_FORMAT_MASKS: u32 = 1;
17pub const NATIVE_DECODER_BATCH_FORMAT_PACKED: u32 = 2;
18pub const NATIVE_DECODER_BATCH_FORMAT_EVENTS: u32 = 3;
19
20#[repr(C)]
21#[derive(Debug, Clone, Copy)]
22pub struct FaultScopeNativeDecoderStringViewV1 {
23    pub ptr: *const c_char,
24    pub len: usize,
25}
26
27impl FaultScopeNativeDecoderStringViewV1 {
28    pub const fn empty() -> Self {
29        Self {
30            ptr: std::ptr::null(),
31            len: 0,
32        }
33    }
34}
35
36#[repr(C)]
37#[derive(Debug, Clone, Copy)]
38pub struct FaultScopeNativeDecoderI64SliceV1 {
39    pub ptr: *const i64,
40    pub len: usize,
41}
42
43impl FaultScopeNativeDecoderI64SliceV1 {
44    pub const fn empty() -> Self {
45        Self {
46            ptr: std::ptr::null(),
47            len: 0,
48        }
49    }
50}
51
52#[repr(C)]
53#[derive(Debug, Clone, Copy)]
54pub struct FaultScopeNativeDecoderU32SliceV1 {
55    pub ptr: *const u32,
56    pub len: usize,
57}
58
59impl FaultScopeNativeDecoderU32SliceV1 {
60    pub const fn empty() -> Self {
61        Self {
62            ptr: std::ptr::null(),
63            len: 0,
64        }
65    }
66}
67
68#[repr(C)]
69#[derive(Debug, Clone, Copy)]
70pub struct FaultScopeNativeDecoderMaskViewV1 {
71    pub words: *const u64,
72    pub word_count: usize,
73}
74
75#[repr(C)]
76#[derive(Debug, Clone, Copy)]
77pub struct FaultScopeNativeDecoderMaskMutViewV1 {
78    pub words: *mut u64,
79    pub word_count: usize,
80}
81
82#[repr(C)]
83#[derive(Debug, Clone, Copy)]
84pub struct FaultScopeNativeDetectorMaskBatchViewV1 {
85    pub detector_ids: *const i64,
86    pub detector_count: usize,
87    pub masks: *const FaultScopeNativeDecoderMaskViewV1,
88    pub shots: usize,
89    pub word_count: usize,
90}
91
92#[repr(C)]
93#[derive(Debug, Clone, Copy)]
94pub struct FaultScopeNativeCorrectionMaskBatchMutViewV1 {
95    pub observable_ids: *const i64,
96    pub observable_count: usize,
97    pub masks: *mut FaultScopeNativeDecoderMaskMutViewV1,
98    pub shots: usize,
99    pub word_count: usize,
100}
101
102#[repr(C)]
103#[derive(Debug, Clone, Copy)]
104pub struct FaultScopeNativePackedDetectorShotBatchViewV1 {
105    pub detector_ids: *const i64,
106    pub detector_count: usize,
107    pub data: *const u8,
108    pub shots: usize,
109    pub detector_byte_count: usize,
110}
111
112#[repr(C)]
113#[derive(Debug, Clone, Copy)]
114pub struct FaultScopeNativeDetectorEventShotBatchViewV1 {
115    pub detector_ids: *const i64,
116    pub detector_count: usize,
117    pub offsets: *const usize,
118    pub offsets_len: usize,
119    pub events: *const usize,
120    pub event_count: usize,
121    pub shots: usize,
122}
123
124#[repr(C)]
125#[derive(Debug, Clone, Copy)]
126pub struct FaultScopeNativePackedObservableShotBatchMutViewV1 {
127    pub observable_ids: *const i64,
128    pub observable_count: usize,
129    pub data: *mut u8,
130    pub shots: usize,
131    pub observable_byte_count: usize,
132}
133
134#[repr(C)]
135#[derive(Debug, Clone, Copy)]
136pub struct FaultScopeNativeDecoderStatusV1 {
137    pub code: i32,
138    pub message: FaultScopeNativeDecoderStringViewV1,
139}
140
141impl FaultScopeNativeDecoderStatusV1 {
142    pub const fn ok() -> Self {
143        Self {
144            code: NATIVE_DECODER_PLUGIN_STATUS_OK,
145            message: FaultScopeNativeDecoderStringViewV1::empty(),
146        }
147    }
148}
149
150#[repr(C)]
151#[derive(Clone, Copy)]
152pub union FaultScopeNativeDetectorBatchPayloadV4 {
153    pub masks: FaultScopeNativeDetectorMaskBatchViewV1,
154    pub packed: FaultScopeNativePackedDetectorShotBatchViewV1,
155    pub events: FaultScopeNativeDetectorEventShotBatchViewV1,
156}
157
158#[repr(C)]
159#[derive(Clone, Copy)]
160pub struct FaultScopeNativeDetectorBatchViewV4 {
161    pub format: u32,
162    pub reserved: u32,
163    pub payload: FaultScopeNativeDetectorBatchPayloadV4,
164}
165
166#[repr(C)]
167#[derive(Clone, Copy)]
168pub union FaultScopeNativeCorrectionBatchPayloadV4 {
169    pub masks: FaultScopeNativeCorrectionMaskBatchMutViewV1,
170    pub packed: FaultScopeNativePackedObservableShotBatchMutViewV1,
171}
172
173#[repr(C)]
174#[derive(Clone, Copy)]
175pub struct FaultScopeNativeCorrectionBatchMutViewV4 {
176    pub format: u32,
177    pub reserved: u32,
178    pub payload: FaultScopeNativeCorrectionBatchPayloadV4,
179}
180
181#[repr(C)]
182#[derive(Clone, Copy)]
183pub struct FaultScopeNativeDecoderFactoryV4 {
184    pub abi_version: u32,
185    pub struct_size: usize,
186    pub flags: u64,
187    pub factory_state: *mut c_void,
188    pub drop_factory_state: Option<unsafe extern "C" fn(*mut c_void)>,
189    pub name: Option<
190        unsafe extern "C" fn(
191            *const c_void,
192            *mut FaultScopeNativeDecoderStringViewV1,
193        ) -> FaultScopeNativeDecoderStatusV1,
194    >,
195    pub detector_ids: Option<
196        unsafe extern "C" fn(
197            *const c_void,
198            *mut FaultScopeNativeDecoderI64SliceV1,
199        ) -> FaultScopeNativeDecoderStatusV1,
200    >,
201    pub observable_ids: Option<
202        unsafe extern "C" fn(
203            *const c_void,
204            *mut FaultScopeNativeDecoderI64SliceV1,
205        ) -> FaultScopeNativeDecoderStatusV1,
206    >,
207    pub batch_formats: Option<
208        unsafe extern "C" fn(
209            *const c_void,
210            *mut FaultScopeNativeDecoderU32SliceV1,
211        ) -> FaultScopeNativeDecoderStatusV1,
212    >,
213    pub create_worker: Option<
214        unsafe extern "C" fn(
215            *const c_void,
216            *mut FaultScopeNativeDecoderWorkerV4,
217            usize,
218        ) -> FaultScopeNativeDecoderStatusV1,
219    >,
220}
221
222#[repr(C)]
223#[derive(Clone, Copy)]
224pub struct FaultScopeNativeDecoderWorkerV4 {
225    pub struct_size: usize,
226    pub worker_state: *mut c_void,
227    pub drop_worker_state: Option<unsafe extern "C" fn(*mut c_void)>,
228    pub decode_batch: Option<
229        unsafe extern "C" fn(
230            *mut c_void,
231            *const FaultScopeNativeDetectorBatchViewV4,
232            *mut FaultScopeNativeCorrectionBatchMutViewV4,
233        ) -> FaultScopeNativeDecoderStatusV1,
234    >,
235}
236
237/// Detector syndrome layouts accepted by native decoders, in preference order.
238#[repr(u32)]
239#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
240pub enum DetectorBatchFormat {
241    Masks = NATIVE_DECODER_BATCH_FORMAT_MASKS,
242    Packed = NATIVE_DECODER_BATCH_FORMAT_PACKED,
243    Events = NATIVE_DECODER_BATCH_FORMAT_EVENTS,
244}
245
246impl DetectorBatchFormat {
247    pub const STABLE_ORDER: [Self; 3] = [Self::Masks, Self::Packed, Self::Events];
248
249    pub const fn correction_format(self) -> Self {
250        match self {
251            Self::Masks => Self::Masks,
252            Self::Packed | Self::Events => Self::Packed,
253        }
254    }
255}
256
257impl TryFrom<u32> for DetectorBatchFormat {
258    type Error = NpError;
259
260    fn try_from(value: u32) -> Result<Self, Self::Error> {
261        match value {
262            NATIVE_DECODER_BATCH_FORMAT_MASKS => Ok(Self::Masks),
263            NATIVE_DECODER_BATCH_FORMAT_PACKED => Ok(Self::Packed),
264            NATIVE_DECODER_BATCH_FORMAT_EVENTS => Ok(Self::Events),
265            _ => Err(NpError::new(format!(
266                "unknown native decoder batch format tag {value}"
267            ))),
268        }
269    }
270}
271
272#[derive(Debug, Clone, Copy)]
273pub struct DetectorMaskBatchView<'a> {
274    pub detector_ids: &'a [i64],
275    pub masks: &'a [Mask],
276    pub shots: usize,
277}
278
279impl<'a> DetectorMaskBatchView<'a> {
280    pub fn new(detector_ids: &'a [i64], masks: &'a [Mask], shots: usize) -> NpResult<Self> {
281        validate_decoder_detector_ids(detector_ids)?;
282        let view = Self {
283            detector_ids,
284            masks,
285            shots,
286        };
287        view.validate_shape()?;
288        Ok(view)
289    }
290
291    fn validate_shape(self) -> NpResult<()> {
292        if self.detector_ids.len() != self.masks.len() {
293            return Err(NpError::new(
294                "detector ids and detector masks must have the same length",
295            ));
296        }
297        let expected_words = crate::word_count(self.shots);
298        for (detector_id, mask) in self.detector_ids.iter().zip(self.masks) {
299            if mask.words.len() != expected_words {
300                return Err(NpError::new(format!(
301                    "detector mask for detector id {detector_id} has {} words; expected {expected_words} for {} shots",
302                    mask.words.len(),
303                    self.shots
304                )));
305            }
306            validate_zero_mask_padding(mask, self.shots, &format!("detector mask {detector_id}"))?;
307        }
308        Ok(())
309    }
310}
311
312#[derive(Debug, Clone, Copy)]
313pub struct PackedDetectorShotBatchView<'a> {
314    pub detector_ids: &'a [i64],
315    pub data: &'a [u8],
316    pub shots: usize,
317    pub detector_byte_count: usize,
318}
319
320#[derive(Debug, Clone, Copy)]
321pub struct DetectorEventShotBatchView<'a> {
322    pub detector_ids: &'a [i64],
323    pub offsets: &'a [usize],
324    pub events: &'a [usize],
325    pub shots: usize,
326}
327
328/// One borrowed detector-syndrome batch tagged with its physical layout.
329#[derive(Debug, Clone, Copy)]
330pub enum DetectorBatchView<'a> {
331    Masks(DetectorMaskBatchView<'a>),
332    Packed(PackedDetectorShotBatchView<'a>),
333    Events(DetectorEventShotBatchView<'a>),
334}
335
336impl<'a> DetectorBatchView<'a> {
337    pub const fn format(self) -> DetectorBatchFormat {
338        match self {
339            Self::Masks(_) => DetectorBatchFormat::Masks,
340            Self::Packed(_) => DetectorBatchFormat::Packed,
341            Self::Events(_) => DetectorBatchFormat::Events,
342        }
343    }
344
345    pub const fn detector_ids(self) -> &'a [i64] {
346        match self {
347            Self::Masks(view) => view.detector_ids,
348            Self::Packed(view) => view.detector_ids,
349            Self::Events(view) => view.detector_ids,
350        }
351    }
352
353    pub const fn shots(self) -> usize {
354        match self {
355            Self::Masks(view) => view.shots,
356            Self::Packed(view) => view.shots,
357            Self::Events(view) => view.shots,
358        }
359    }
360
361    pub fn validate(self) -> NpResult<()> {
362        validate_decoder_detector_ids(self.detector_ids())?;
363        self.validate_shape()
364    }
365
366    pub(crate) fn validate_shape(self) -> NpResult<()> {
367        match self {
368            Self::Masks(view) => view.validate_shape()?,
369            Self::Packed(view) => {
370                view.validate_shape()?;
371            }
372            Self::Events(view) => view.validate_shape()?,
373        }
374        Ok(())
375    }
376}
377
378impl<'a> From<DetectorMaskBatchView<'a>> for DetectorBatchView<'a> {
379    fn from(value: DetectorMaskBatchView<'a>) -> Self {
380        Self::Masks(value)
381    }
382}
383
384impl<'a> From<PackedDetectorShotBatchView<'a>> for DetectorBatchView<'a> {
385    fn from(value: PackedDetectorShotBatchView<'a>) -> Self {
386        Self::Packed(value)
387    }
388}
389
390impl<'a> From<DetectorEventShotBatchView<'a>> for DetectorBatchView<'a> {
391    fn from(value: DetectorEventShotBatchView<'a>) -> Self {
392        Self::Events(value)
393    }
394}
395
396impl<'a> DetectorEventShotBatchView<'a> {
397    pub fn new(
398        detector_ids: &'a [i64],
399        offsets: &'a [usize],
400        events: &'a [usize],
401        shots: usize,
402    ) -> NpResult<Self> {
403        validate_decoder_detector_ids(detector_ids)?;
404        let view = Self {
405            detector_ids,
406            offsets,
407            events,
408            shots,
409        };
410        view.validate_shape()?;
411        Ok(view)
412    }
413
414    fn validate_shape(self) -> NpResult<()> {
415        let expected_offsets_len = self
416            .shots
417            .checked_add(1)
418            .ok_or_else(|| NpError::new("detector event batch offset length overflowed usize"))?;
419        if self.offsets.len() != expected_offsets_len {
420            return Err(NpError::new(format!(
421                "detector event batch offsets has length {}; expected {}",
422                self.offsets.len(),
423                expected_offsets_len
424            )));
425        }
426        if self.offsets.first().copied().unwrap_or(0) != 0
427            || self.offsets.last().copied().unwrap_or(0) != self.events.len()
428        {
429            return Err(NpError::new(
430                "detector event batch offsets must start at 0 and end at events length",
431            ));
432        }
433        for pair in self.offsets.windows(2) {
434            if pair[0] > pair[1] {
435                return Err(NpError::new(
436                    "detector event batch offsets must be nondecreasing",
437                ));
438            }
439        }
440        for &event in self.events {
441            if event >= self.detector_ids.len() {
442                return Err(NpError::new(format!(
443                    "detector event index {event} exceeds detector count {}",
444                    self.detector_ids.len()
445                )));
446            }
447        }
448        Ok(())
449    }
450}
451
452impl<'a> PackedDetectorShotBatchView<'a> {
453    pub fn new(detector_ids: &'a [i64], data: &'a [u8], shots: usize) -> NpResult<Self> {
454        validate_decoder_detector_ids(detector_ids)?;
455        let view = Self {
456            detector_ids,
457            data,
458            shots,
459            detector_byte_count: detector_ids.len().div_ceil(8),
460        };
461        view.validate_shape()?;
462        Ok(view)
463    }
464
465    fn validate_shape(self) -> NpResult<()> {
466        let expected_byte_count = self.detector_ids.len().div_ceil(8);
467        if self.detector_byte_count != expected_byte_count {
468            return Err(NpError::new(format!(
469                "packed detector byte count is {}; expected {expected_byte_count}",
470                self.detector_byte_count
471            )));
472        }
473        let expected_len = self.shots.checked_mul(expected_byte_count).ok_or_else(|| {
474            NpError::new("packed detector shot batch byte length overflowed usize")
475        })?;
476        if self.data.len() != expected_len {
477            return Err(NpError::new(format!(
478                "packed detector shot batch has {} bytes; expected {expected_len} for {} shots and {} detectors",
479                self.data.len(),
480                self.shots,
481                self.detector_ids.len()
482            )));
483        }
484        validate_zero_packed_padding(
485            self.data,
486            self.shots,
487            expected_byte_count,
488            self.detector_ids.len(),
489            "packed detector batch",
490        )?;
491        Ok(())
492    }
493}
494
495/// Owned detector syndrome storage used when a producer and decoder negotiate a layout.
496#[derive(Debug, Clone, PartialEq)]
497pub enum DetectorBatch {
498    Masks {
499        detector_ids: Vec<i64>,
500        masks: Vec<Mask>,
501        shots: usize,
502    },
503    Packed {
504        detector_ids: Vec<i64>,
505        data: Vec<u8>,
506        shots: usize,
507        detector_byte_count: usize,
508    },
509    Events {
510        detector_ids: Vec<i64>,
511        offsets: Vec<usize>,
512        events: Vec<usize>,
513        shots: usize,
514    },
515}
516
517impl DetectorBatch {
518    pub const fn format(&self) -> DetectorBatchFormat {
519        match self {
520            Self::Masks { .. } => DetectorBatchFormat::Masks,
521            Self::Packed { .. } => DetectorBatchFormat::Packed,
522            Self::Events { .. } => DetectorBatchFormat::Events,
523        }
524    }
525
526    pub fn detector_ids(&self) -> &[i64] {
527        match self {
528            Self::Masks { detector_ids, .. }
529            | Self::Packed { detector_ids, .. }
530            | Self::Events { detector_ids, .. } => detector_ids,
531        }
532    }
533
534    pub const fn shots(&self) -> usize {
535        match self {
536            Self::Masks { shots, .. } | Self::Packed { shots, .. } | Self::Events { shots, .. } => {
537                *shots
538            }
539        }
540    }
541
542    pub fn view(&self) -> DetectorBatchView<'_> {
543        match self {
544            Self::Masks {
545                detector_ids,
546                masks,
547                shots,
548            } => DetectorBatchView::Masks(DetectorMaskBatchView {
549                detector_ids,
550                masks,
551                shots: *shots,
552            }),
553            Self::Packed {
554                detector_ids,
555                data,
556                shots,
557                detector_byte_count,
558            } => DetectorBatchView::Packed(PackedDetectorShotBatchView {
559                detector_ids,
560                data,
561                shots: *shots,
562                detector_byte_count: *detector_byte_count,
563            }),
564            Self::Events {
565                detector_ids,
566                offsets,
567                events,
568                shots,
569            } => DetectorBatchView::Events(DetectorEventShotBatchView {
570                detector_ids,
571                offsets,
572                events,
573                shots: *shots,
574            }),
575        }
576    }
577
578    pub fn validate(&self) -> NpResult<()> {
579        self.view().validate()
580    }
581
582    pub(crate) fn validate_shape(&self) -> NpResult<()> {
583        self.view().validate_shape()
584    }
585}
586
587pub(crate) fn empty_detector_event_offsets(shots: usize) -> NpResult<Vec<usize>> {
588    let offset_count = shots
589        .checked_add(1)
590        .ok_or_else(|| NpError::new("detector event offset length overflowed usize"))?;
591    let mut offsets = Vec::new();
592    offsets.try_reserve_exact(offset_count).map_err(|error| {
593        NpError::new(format!(
594            "detector event offset storage for {shots} shots could not be allocated: {error}"
595        ))
596    })?;
597    offsets.push(0);
598    Ok(offsets)
599}
600
601/// Convert a detector syndrome without changing its detector ID order or GF(2) value.
602///
603/// Duplicate indices in an Events input are combined with XOR. Events output is
604/// canonical: each non-zero detector occurs exactly once per shot.
605pub fn convert_detector_batch(
606    source: DetectorBatchView<'_>,
607    target: DetectorBatchFormat,
608) -> NpResult<DetectorBatch> {
609    convert_detector_batch_impl(source, target, true)
610}
611
612fn convert_detector_batch_prevalidated(
613    source: DetectorBatchView<'_>,
614    target: DetectorBatchFormat,
615) -> NpResult<DetectorBatch> {
616    convert_detector_batch_impl(source, target, false)
617}
618
619fn convert_detector_batch_impl(
620    source: DetectorBatchView<'_>,
621    target: DetectorBatchFormat,
622    validate_metadata: bool,
623) -> NpResult<DetectorBatch> {
624    if validate_metadata {
625        source.validate()?;
626    } else {
627        source.validate_shape()?;
628    }
629    let detector_ids = source.detector_ids().to_vec();
630    let shots = source.shots();
631    let detector_count = detector_ids.len();
632    let detector_byte_count = detector_count.div_ceil(8);
633    let words = crate::word_count(shots);
634
635    let converted = match (source, target) {
636        (DetectorBatchView::Masks(view), DetectorBatchFormat::Masks) => DetectorBatch::Masks {
637            detector_ids,
638            masks: view.masks.to_vec(),
639            shots,
640        },
641        (DetectorBatchView::Packed(view), DetectorBatchFormat::Packed) => DetectorBatch::Packed {
642            detector_ids,
643            data: view.data.to_vec(),
644            shots,
645            detector_byte_count,
646        },
647        (DetectorBatchView::Events(view), DetectorBatchFormat::Events) => {
648            let mut offsets = empty_detector_event_offsets(shots)?;
649            let mut events = Vec::new();
650            let mut parity = vec![false; detector_count];
651            for shot in 0..shots {
652                parity.fill(false);
653                for &detector in &view.events[view.offsets[shot]..view.offsets[shot + 1]] {
654                    parity[detector] ^= true;
655                }
656                events.extend(
657                    parity
658                        .iter()
659                        .enumerate()
660                        .filter_map(|(detector, set)| set.then_some(detector)),
661                );
662                offsets.push(events.len());
663            }
664            DetectorBatch::Events {
665                detector_ids,
666                offsets,
667                events,
668                shots,
669            }
670        }
671        (DetectorBatchView::Masks(view), DetectorBatchFormat::Packed) => {
672            let len = shots.checked_mul(detector_byte_count).ok_or_else(|| {
673                NpError::new("packed detector conversion length overflowed usize")
674            })?;
675            let mut data = vec![0u8; len];
676            for (detector, mask) in view.masks.iter().enumerate() {
677                for shot in 0..shots {
678                    if mask.words[shot >> 6] & (1u64 << (shot & 63)) != 0 {
679                        data[shot * detector_byte_count + (detector >> 3)] |= 1u8 << (detector & 7);
680                    }
681                }
682            }
683            DetectorBatch::Packed {
684                detector_ids,
685                data,
686                shots,
687                detector_byte_count,
688            }
689        }
690        (DetectorBatchView::Packed(view), DetectorBatchFormat::Masks) => {
691            let mut masks = vec![Mask::zero(words); detector_count];
692            for shot in 0..shots {
693                let row = shot * detector_byte_count;
694                for (detector, mask) in masks.iter_mut().enumerate() {
695                    if view.data[row + (detector >> 3)] & (1u8 << (detector & 7)) != 0 {
696                        mask.words[shot >> 6] |= 1u64 << (shot & 63);
697                    }
698                }
699            }
700            DetectorBatch::Masks {
701                detector_ids,
702                masks,
703                shots,
704            }
705        }
706        (DetectorBatchView::Events(view), DetectorBatchFormat::Masks) => {
707            let mut masks = vec![Mask::zero(words); detector_count];
708            for shot in 0..shots {
709                for &detector in &view.events[view.offsets[shot]..view.offsets[shot + 1]] {
710                    masks[detector].words[shot >> 6] ^= 1u64 << (shot & 63);
711                }
712            }
713            DetectorBatch::Masks {
714                detector_ids,
715                masks,
716                shots,
717            }
718        }
719        (DetectorBatchView::Events(view), DetectorBatchFormat::Packed) => {
720            let len = shots.checked_mul(detector_byte_count).ok_or_else(|| {
721                NpError::new("packed detector conversion length overflowed usize")
722            })?;
723            let mut data = vec![0u8; len];
724            for shot in 0..shots {
725                let row = shot * detector_byte_count;
726                for &detector in &view.events[view.offsets[shot]..view.offsets[shot + 1]] {
727                    data[row + (detector >> 3)] ^= 1u8 << (detector & 7);
728                }
729            }
730            DetectorBatch::Packed {
731                detector_ids,
732                data,
733                shots,
734                detector_byte_count,
735            }
736        }
737        (DetectorBatchView::Masks(view), DetectorBatchFormat::Events) => {
738            let mut offsets = empty_detector_event_offsets(shots)?;
739            let mut events = Vec::new();
740            for shot in 0..shots {
741                for (detector, mask) in view.masks.iter().enumerate() {
742                    if mask.words[shot >> 6] & (1u64 << (shot & 63)) != 0 {
743                        events.push(detector);
744                    }
745                }
746                offsets.push(events.len());
747            }
748            DetectorBatch::Events {
749                detector_ids,
750                offsets,
751                events,
752                shots,
753            }
754        }
755        (DetectorBatchView::Packed(view), DetectorBatchFormat::Events) => {
756            let mut offsets = empty_detector_event_offsets(shots)?;
757            let mut events = Vec::new();
758            for shot in 0..shots {
759                let row = shot * detector_byte_count;
760                for detector in 0..detector_count {
761                    if view.data[row + (detector >> 3)] & (1u8 << (detector & 7)) != 0 {
762                        events.push(detector);
763                    }
764                }
765                offsets.push(events.len());
766            }
767            DetectorBatch::Events {
768                detector_ids,
769                offsets,
770                events,
771                shots,
772            }
773        }
774    };
775    if validate_metadata {
776        converted.validate()?;
777    } else {
778        converted.validate_shape()?;
779    }
780    Ok(converted)
781}
782
783#[derive(Debug, Clone, PartialEq)]
784pub struct PackedObservableShotBatch {
785    pub observable_ids: Vec<i64>,
786    pub data: Vec<u8>,
787    pub shots: usize,
788    pub observable_byte_count: usize,
789}
790
791impl PackedObservableShotBatch {
792    pub fn new(observable_ids: Vec<i64>, data: Vec<u8>, shots: usize) -> NpResult<Self> {
793        let observable_byte_count = observable_ids.len().div_ceil(8);
794        let batch = Self {
795            observable_ids,
796            data,
797            shots,
798            observable_byte_count,
799        };
800        batch.validate_shape()?;
801        Ok(batch)
802    }
803
804    pub fn zero(observable_ids: Vec<i64>, shots: usize) -> NpResult<Self> {
805        let observable_byte_count = observable_ids.len().div_ceil(8);
806        let len = shots
807            .checked_mul(observable_byte_count)
808            .ok_or_else(|| NpError::new("packed correction byte length overflowed usize"))?;
809        let mut data = Vec::new();
810        data.try_reserve_exact(len).map_err(|error| {
811            NpError::new(format!(
812                "packed correction storage for {shots} shots could not be allocated: {error}"
813            ))
814        })?;
815        data.resize(len, 0);
816        Self::new(observable_ids, data, shots)
817    }
818
819    pub fn validate_against(&self, declared_observable_ids: &[i64], shots: usize) -> NpResult<()> {
820        if self.shots != shots {
821            return Err(NpError::new(format!(
822                "packed correction batch has {} shots; expected {shots}",
823                self.shots
824            )));
825        }
826        self.validate_shape()?;
827        if self.observable_ids != declared_observable_ids {
828            return Err(NpError::new(format!(
829                "packed correction observable layout mismatch: expected {:?}, got {:?}",
830                declared_observable_ids, self.observable_ids
831            )));
832        }
833        Ok(())
834    }
835
836    fn validate_shape(&self) -> NpResult<()> {
837        let expected_byte_count = self.observable_ids.len().div_ceil(8);
838        if self.observable_byte_count != expected_byte_count {
839            return Err(NpError::new(format!(
840                "packed correction observable byte count is {}; expected {expected_byte_count}",
841                self.observable_byte_count
842            )));
843        }
844        let expected_len = self
845            .shots
846            .checked_mul(self.observable_byte_count)
847            .ok_or_else(|| NpError::new("packed correction byte length overflowed usize"))?;
848        if self.data.len() != expected_len {
849            return Err(NpError::new(format!(
850                "packed correction batch has {} bytes; expected {expected_len} for {} shots and {} observables",
851                self.data.len(),
852                self.shots,
853                self.observable_ids.len()
854            )));
855        }
856        for (index, observable_id) in self.observable_ids.iter().enumerate() {
857            if self.observable_ids[..index].contains(observable_id) {
858                return Err(NpError::new(format!(
859                    "duplicate packed correction observable id {observable_id}"
860                )));
861            }
862        }
863        validate_zero_packed_padding(
864            &self.data,
865            self.shots,
866            self.observable_byte_count,
867            self.observable_ids.len(),
868            "packed correction batch",
869        )?;
870        Ok(())
871    }
872}
873
874fn validate_zero_packed_padding(
875    data: &[u8],
876    shots: usize,
877    byte_count: usize,
878    bit_count: usize,
879    batch_name: &str,
880) -> NpResult<()> {
881    let used_bits = bit_count & 7;
882    if used_bits == 0 {
883        return Ok(());
884    }
885    let padding_mask = !((1u8 << used_bits) - 1);
886    for shot in 0..shots {
887        let final_byte = data[(shot + 1) * byte_count - 1];
888        if final_byte & padding_mask != 0 {
889            return Err(NpError::new(format!(
890                "{batch_name} shot {shot} has non-zero padding bits"
891            )));
892        }
893    }
894    Ok(())
895}
896
897fn validate_zero_mask_padding(mask: &Mask, shots: usize, name: &str) -> NpResult<()> {
898    let used_bits = shots & 63;
899    if used_bits == 0 {
900        return Ok(());
901    }
902    let padding_mask = !((1u64 << used_bits) - 1);
903    if mask.words.last().copied().unwrap_or(0) & padding_mask != 0 {
904        return Err(NpError::new(format!(
905            "{name} has non-zero padding bits for {shots} shots"
906        )));
907    }
908    Ok(())
909}
910
911/// Count shots whose packed observable bits disagree with packed corrections.
912///
913/// Both inputs must use the same canonical observable layout and zero their
914/// unused padding bits.
915pub fn packed_residual_failure_count(
916    observable_ids: &[i64],
917    observable_data: &[u8],
918    observable_byte_count: usize,
919    corrections: &PackedObservableShotBatch,
920    shots: usize,
921) -> NpResult<usize> {
922    let expected_observable_byte_count = observable_ids.len().div_ceil(8);
923    if observable_byte_count != expected_observable_byte_count {
924        return Err(NpError::new(format!(
925            "packed observable byte count is {observable_byte_count}; expected {expected_observable_byte_count}"
926        )));
927    }
928    let expected_observable_data_len = shots
929        .checked_mul(observable_byte_count)
930        .ok_or_else(|| NpError::new("packed observable byte length overflowed usize"))?;
931    if observable_data.len() != expected_observable_data_len {
932        return Err(NpError::new(format!(
933            "packed observable batch has {} bytes; expected {expected_observable_data_len} for {shots} shots and {} observables",
934            observable_data.len(),
935            observable_ids.len()
936        )));
937    }
938    validate_zero_packed_padding(
939        observable_data,
940        shots,
941        observable_byte_count,
942        observable_ids.len(),
943        "packed observable batch",
944    )?;
945    corrections.validate_against(observable_ids, shots)?;
946
947    Ok((0..shots)
948        .filter(|shot| {
949            let begin = shot * observable_byte_count;
950            let end = begin + observable_byte_count;
951            observable_data[begin..end]
952                .iter()
953                .zip(&corrections.data[begin..end])
954                .any(|(actual, correction)| (actual ^ correction) != 0)
955        })
956        .count())
957}
958
959#[derive(Debug, Clone, PartialEq)]
960pub struct CorrectionMaskBatch {
961    pub observable_ids: Vec<i64>,
962    pub masks: Vec<Mask>,
963    pub shots: usize,
964}
965
966impl CorrectionMaskBatch {
967    pub fn new(observable_ids: Vec<i64>, masks: Vec<Mask>, shots: usize) -> NpResult<Self> {
968        if observable_ids.len() != masks.len() {
969            return Err(NpError::new(
970                "observable ids and correction masks must have the same length",
971            ));
972        }
973        let batch = Self {
974            observable_ids,
975            masks,
976            shots,
977        };
978        batch.validate_shape()?;
979        Ok(batch)
980    }
981
982    pub fn empty(shots: usize) -> Self {
983        Self {
984            observable_ids: Vec::new(),
985            masks: Vec::new(),
986            shots,
987        }
988    }
989
990    pub fn get(&self, observable_id: i64) -> Option<&Mask> {
991        self.observable_ids
992            .iter()
993            .position(|id| *id == observable_id)
994            .and_then(|index| self.masks.get(index))
995    }
996
997    pub fn validate_against(&self, declared_observable_ids: &[i64], shots: usize) -> NpResult<()> {
998        if self.shots != shots {
999            return Err(NpError::new(format!(
1000                "correction batch has {} shots; expected {shots}",
1001                self.shots
1002            )));
1003        }
1004        self.validate_shape()?;
1005        if self.observable_ids != declared_observable_ids {
1006            return Err(NpError::new(format!(
1007                "correction observable layout mismatch: expected {:?}, got {:?}",
1008                declared_observable_ids, self.observable_ids
1009            )));
1010        }
1011        Ok(())
1012    }
1013
1014    fn validate_shape(&self) -> NpResult<()> {
1015        if self.observable_ids.len() != self.masks.len() {
1016            return Err(NpError::new(
1017                "observable ids and correction masks must have the same length",
1018            ));
1019        }
1020        let expected_words = crate::word_count(self.shots);
1021        for (observable_id, mask) in self.observable_ids.iter().zip(&self.masks) {
1022            if mask.words.len() != expected_words {
1023                return Err(NpError::new(format!(
1024                    "correction mask for observable id {observable_id} has {} words; expected {expected_words} for {} shots",
1025                    mask.words.len(),
1026                    self.shots
1027                )));
1028            }
1029            validate_zero_mask_padding(
1030                mask,
1031                self.shots,
1032                &format!("correction mask {observable_id}"),
1033            )?;
1034        }
1035        for (index, observable_id) in self.observable_ids.iter().enumerate() {
1036            if self.observable_ids[..index].contains(observable_id) {
1037                return Err(NpError::new(format!(
1038                    "duplicate correction observable id {observable_id}"
1039                )));
1040            }
1041        }
1042        Ok(())
1043    }
1044}
1045
1046/// Decoder output tagged with the only two correction layouts allowed by V4.
1047#[derive(Debug, Clone, PartialEq)]
1048pub enum DecoderCorrectionBatch {
1049    Masks(CorrectionMaskBatch),
1050    Packed(PackedObservableShotBatch),
1051}
1052
1053impl DecoderCorrectionBatch {
1054    pub const fn format(&self) -> DetectorBatchFormat {
1055        match self {
1056            Self::Masks(_) => DetectorBatchFormat::Masks,
1057            Self::Packed(_) => DetectorBatchFormat::Packed,
1058        }
1059    }
1060
1061    pub const fn shots(&self) -> usize {
1062        match self {
1063            Self::Masks(batch) => batch.shots,
1064            Self::Packed(batch) => batch.shots,
1065        }
1066    }
1067
1068    pub fn validate_against(&self, observable_ids: &[i64], shots: usize) -> NpResult<()> {
1069        match self {
1070            Self::Masks(batch) => batch.validate_against(observable_ids, shots),
1071            Self::Packed(batch) => batch.validate_against(observable_ids, shots),
1072        }
1073    }
1074
1075    pub fn into_masks(self) -> NpResult<CorrectionMaskBatch> {
1076        match self {
1077            Self::Masks(batch) => Ok(batch),
1078            Self::Packed(batch) => packed_corrections_to_masks(batch),
1079        }
1080    }
1081
1082    pub fn into_packed(self) -> NpResult<PackedObservableShotBatch> {
1083        match self {
1084            Self::Masks(batch) => mask_corrections_to_packed(batch),
1085            Self::Packed(batch) => Ok(batch),
1086        }
1087    }
1088}
1089
1090pub fn mask_corrections_to_packed(
1091    batch: CorrectionMaskBatch,
1092) -> NpResult<PackedObservableShotBatch> {
1093    batch.validate_shape()?;
1094    let observable_byte_count = batch.observable_ids.len().div_ceil(8);
1095    let len = batch
1096        .shots
1097        .checked_mul(observable_byte_count)
1098        .ok_or_else(|| NpError::new("packed correction conversion length overflowed usize"))?;
1099    let mut data = vec![0u8; len];
1100    for (observable, mask) in batch.masks.iter().enumerate() {
1101        for shot in 0..batch.shots {
1102            if mask.words[shot >> 6] & (1u64 << (shot & 63)) != 0 {
1103                data[shot * observable_byte_count + (observable >> 3)] |= 1u8 << (observable & 7);
1104            }
1105        }
1106    }
1107    PackedObservableShotBatch::new(batch.observable_ids, data, batch.shots)
1108}
1109
1110pub fn packed_corrections_to_masks(
1111    batch: PackedObservableShotBatch,
1112) -> NpResult<CorrectionMaskBatch> {
1113    batch.validate_shape()?;
1114    let mut masks = vec![Mask::zero(crate::word_count(batch.shots)); batch.observable_ids.len()];
1115    for shot in 0..batch.shots {
1116        let row = shot * batch.observable_byte_count;
1117        for (observable, mask) in masks.iter_mut().enumerate() {
1118            if batch.data[row + (observable >> 3)] & (1u8 << (observable & 7)) != 0 {
1119                mask.words[shot >> 6] |= 1u64 << (shot & 63);
1120            }
1121        }
1122    }
1123    CorrectionMaskBatch::new(batch.observable_ids, masks, batch.shots)
1124}
1125
1126pub trait NativeDecoderFactory: Send + Sync {
1127    fn name(&self) -> &str;
1128    /// Ordered detector input layout. Detector ids must be unique.
1129    fn detector_ids(&self) -> &[i64];
1130    fn observable_ids(&self) -> &[i64];
1131    /// Stable, non-empty, duplicate-free format preference list.
1132    fn batch_formats(&self) -> &[DetectorBatchFormat];
1133    fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>>;
1134}
1135
1136pub trait NativeDecoderWorker: Send {
1137    fn name(&self) -> &str;
1138    /// Ordered detector input layout. Detector ids must be unique.
1139    fn detector_ids(&self) -> &[i64];
1140    fn observable_ids(&self) -> &[i64];
1141    /// Stable, non-empty, duplicate-free format preference list.
1142    fn batch_formats(&self) -> &[DetectorBatchFormat];
1143    fn decode_batch(
1144        &mut self,
1145        detectors: DetectorBatchView<'_>,
1146    ) -> NpResult<DecoderCorrectionBatch>;
1147
1148    fn decode_batch_checked(
1149        &mut self,
1150        detectors: DetectorBatchView<'_>,
1151    ) -> NpResult<DecoderCorrectionBatch> {
1152        validate_decoder_batch_formats(self.batch_formats())?;
1153        detectors.validate_shape()?;
1154        if detectors.detector_ids() != self.detector_ids() {
1155            return Err(NpError::new(format!(
1156                "decoder `{}` received detector ids {:?}; expected {:?}",
1157                self.name(),
1158                detectors.detector_ids(),
1159                self.detector_ids()
1160            )));
1161        }
1162        if !self.batch_formats().contains(&detectors.format()) {
1163            return Err(NpError::new(format!(
1164                "decoder `{}` does not declare support for {:?} detector batches",
1165                self.name(),
1166                detectors.format()
1167            )));
1168        }
1169        let shots = detectors.shots();
1170        let expected_format = detectors.format().correction_format();
1171        let corrections = self.decode_batch(detectors)?;
1172        if corrections.format() != expected_format {
1173            return Err(NpError::new(format!(
1174                "decoder `{}` returned {:?} corrections for {:?} detector input; expected {:?} corrections",
1175                self.name(),
1176                corrections.format(),
1177                detectors.format(),
1178                expected_format
1179            )));
1180        }
1181        corrections.validate_against(self.observable_ids(), shots)?;
1182        Ok(corrections)
1183    }
1184}
1185
1186/// Validate a decoder's ordered format preference metadata.
1187pub fn validate_decoder_batch_formats(formats: &[DetectorBatchFormat]) -> NpResult<()> {
1188    if formats.is_empty() {
1189        return Err(NpError::new(
1190            "native decoder batch format preference list must not be empty",
1191        ));
1192    }
1193    let mut seen = [false; 3];
1194    for &format in formats {
1195        let index = match format {
1196            DetectorBatchFormat::Masks => 0,
1197            DetectorBatchFormat::Packed => 1,
1198            DetectorBatchFormat::Events => 2,
1199        };
1200        if std::mem::replace(&mut seen[index], true) {
1201            return Err(NpError::new(format!(
1202                "native decoder batch format preference list contains duplicate format {format:?}"
1203            )));
1204        }
1205    }
1206    Ok(())
1207}
1208
1209/// Select the first decoder preference a producer can emit without conversion.
1210/// If there is no direct intersection, the decoder's first preference wins.
1211pub fn select_detector_batch_format(
1212    decoder_formats: &[DetectorBatchFormat],
1213    producer_formats: &[DetectorBatchFormat],
1214) -> NpResult<DetectorBatchFormat> {
1215    validate_decoder_batch_formats(decoder_formats)?;
1216    if producer_formats.is_empty() {
1217        return Err(NpError::new(
1218            "detector batch producer format list must not be empty",
1219        ));
1220    }
1221    Ok(decoder_formats
1222        .iter()
1223        .copied()
1224        .find(|format| producer_formats.contains(format))
1225        .unwrap_or(decoder_formats[0]))
1226}
1227
1228const MASKS_BATCH_FORMATS: [DetectorBatchFormat; 1] = [DetectorBatchFormat::Masks];
1229#[cfg(feature = "decoder-fusion-blossom")]
1230const PACKED_BATCH_FORMATS: [DetectorBatchFormat; 1] = [DetectorBatchFormat::Packed];
1231const ALL_BATCH_FORMATS: [DetectorBatchFormat; 3] = DetectorBatchFormat::STABLE_ORDER;
1232
1233/// Validate the ordered detector input layout exposed by a decoder.
1234pub fn validate_decoder_detector_ids(detector_ids: &[i64]) -> NpResult<()> {
1235    validate_decoder_ids(detector_ids, "detector")
1236}
1237
1238/// Validate the ordered logical-observable output layout exposed by a decoder.
1239pub fn validate_decoder_observable_ids(observable_ids: &[i64]) -> NpResult<()> {
1240    validate_decoder_ids(observable_ids, "observable")
1241}
1242
1243fn validate_decoder_ids(ids: &[i64], kind: &str) -> NpResult<()> {
1244    let mut seen = HashSet::with_capacity(ids.len());
1245    for &id in ids {
1246        if !seen.insert(id) {
1247            return Err(NpError::new(format!(
1248                "decoder {kind} ids must be unique; duplicate {kind} id {id}"
1249            )));
1250        }
1251    }
1252    Ok(())
1253}
1254
1255pub struct NativeCompositeDecoder {
1256    children: Vec<Arc<dyn NativeDecoderFactory>>,
1257    detector_ids: Vec<i64>,
1258    observable_ids: Vec<i64>,
1259    observable_indices: HashMap<i64, usize>,
1260    child_plans: Vec<CompositeChildPlan>,
1261    batch_formats: Vec<DetectorBatchFormat>,
1262}
1263
1264#[derive(Clone)]
1265struct CompositeChildPlan {
1266    detector_indices: Vec<usize>,
1267    detector_ids: Vec<i64>,
1268    global_to_local: Vec<Option<usize>>,
1269}
1270
1271impl std::fmt::Debug for NativeCompositeDecoder {
1272    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1273        formatter
1274            .debug_struct("NativeCompositeDecoder")
1275            .field("detector_ids", &self.detector_ids)
1276            .field("observable_ids", &self.observable_ids)
1277            .field("child_count", &self.children.len())
1278            .finish()
1279    }
1280}
1281
1282impl NativeCompositeDecoder {
1283    pub fn new(children: Vec<Arc<dyn NativeDecoderFactory>>) -> NpResult<Self> {
1284        if children.is_empty() {
1285            return Err(NpError::new(
1286                "native composite decoder requires at least one child decoder",
1287            ));
1288        }
1289        let mut detector_ids = Vec::new();
1290        let mut detector_indices = HashMap::new();
1291        let mut observable_ids = Vec::new();
1292        let mut seen_observables = HashSet::new();
1293        let mut child_detector_indices = Vec::with_capacity(children.len());
1294        for (child_index, child) in children.iter().enumerate() {
1295            validate_decoder_batch_formats(child.batch_formats()).map_err(|err| {
1296                NpError::new(format!(
1297                    "native composite decoder child {child_index} (`{}`) has invalid batch format metadata: {}",
1298                    child.name(),
1299                    err.message()
1300                ))
1301            })?;
1302            validate_decoder_detector_ids(child.detector_ids()).map_err(|err| {
1303                NpError::new(format!(
1304                    "native composite decoder child {child_index} (`{}`) has invalid detector metadata: {}",
1305                    child.name(),
1306                    err.message()
1307                ))
1308            })?;
1309            let mut indices = Vec::with_capacity(child.detector_ids().len());
1310            for &detector_id in child.detector_ids() {
1311                let index = *detector_indices.entry(detector_id).or_insert_with(|| {
1312                    let index = detector_ids.len();
1313                    detector_ids.push(detector_id);
1314                    index
1315                });
1316                indices.push(index);
1317            }
1318            child_detector_indices.push(indices);
1319            for &observable_id in child.observable_ids() {
1320                if !seen_observables.insert(observable_id) {
1321                    return Err(NpError::new(format!(
1322                        "native composite decoder has duplicate observable id {observable_id}"
1323                    )));
1324                }
1325                observable_ids.push(observable_id);
1326            }
1327        }
1328        let observable_indices = observable_ids
1329            .iter()
1330            .copied()
1331            .enumerate()
1332            .map(|(index, id)| (id, index))
1333            .collect();
1334        let child_plans = child_detector_indices
1335            .into_iter()
1336            .map(|detector_indices| {
1337                let mut mapping = vec![None; detector_ids.len()];
1338                for (local, &global) in detector_indices.iter().enumerate() {
1339                    mapping[global] = Some(local);
1340                }
1341                let child_detector_ids = detector_indices
1342                    .iter()
1343                    .map(|&index| detector_ids[index])
1344                    .collect();
1345                CompositeChildPlan {
1346                    detector_indices,
1347                    detector_ids: child_detector_ids,
1348                    global_to_local: mapping,
1349                }
1350            })
1351            .collect();
1352        let mut batch_formats = DetectorBatchFormat::STABLE_ORDER.to_vec();
1353        batch_formats.sort_by_key(|format| {
1354            let conversion_count = children
1355                .iter()
1356                .filter(|child| !child.batch_formats().contains(format))
1357                .count();
1358            let preference_rank = children
1359                .iter()
1360                .map(|child| {
1361                    child
1362                        .batch_formats()
1363                        .iter()
1364                        .position(|candidate| candidate == format)
1365                        .unwrap_or(0)
1366                })
1367                .sum::<usize>();
1368            let stable_rank = DetectorBatchFormat::STABLE_ORDER
1369                .iter()
1370                .position(|candidate| candidate == format)
1371                .expect("candidate is in the stable format order");
1372            (conversion_count, preference_rank, stable_rank)
1373        });
1374        Ok(Self {
1375            children,
1376            detector_ids,
1377            observable_ids,
1378            observable_indices,
1379            child_plans,
1380            batch_formats,
1381        })
1382    }
1383}
1384
1385impl NativeDecoderFactory for NativeCompositeDecoder {
1386    fn name(&self) -> &str {
1387        "composite"
1388    }
1389
1390    fn detector_ids(&self) -> &[i64] {
1391        &self.detector_ids
1392    }
1393
1394    fn observable_ids(&self) -> &[i64] {
1395        &self.observable_ids
1396    }
1397
1398    fn batch_formats(&self) -> &[DetectorBatchFormat] {
1399        &self.batch_formats
1400    }
1401
1402    fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
1403        let children = self
1404            .children
1405            .iter()
1406            .enumerate()
1407            .map(|(index, child)| {
1408                let worker = child.create_worker().map_err(|err| {
1409                    NpError::new(format!(
1410                        "composite decoder `{}` child {index} (`{}`) worker factory failed: {}",
1411                        self.name(),
1412                        child.name(),
1413                        err.message()
1414                    ))
1415                })?;
1416                if worker.name() != child.name() {
1417                    return Err(NpError::new(format!(
1418                        "composite decoder `{}` child {index} (`{}`) worker name `{}` does not match factory name",
1419                        self.name(),
1420                        child.name(),
1421                        worker.name()
1422                    )));
1423                }
1424                if worker.detector_ids() != child.detector_ids() {
1425                    return Err(NpError::new(format!(
1426                        "composite decoder `{}` child {index} (`{}`) worker detector ids {:?} do not match factory detector ids {:?}",
1427                        self.name(),
1428                        child.name(),
1429                        worker.detector_ids(),
1430                        child.detector_ids()
1431                    )));
1432                }
1433                if worker.observable_ids() != child.observable_ids() {
1434                    return Err(NpError::new(format!(
1435                        "composite decoder `{}` child {index} (`{}`) worker observable ids {:?} do not match factory observable ids {:?}",
1436                        self.name(),
1437                        child.name(),
1438                        worker.observable_ids(),
1439                        child.observable_ids()
1440                    )));
1441                }
1442                validate_decoder_batch_formats(worker.batch_formats())?;
1443                if worker.batch_formats() != child.batch_formats() {
1444                    return Err(NpError::new(format!(
1445                        "composite decoder `{}` child {index} (`{}`) worker batch formats {:?} do not match factory batch formats {:?}",
1446                        self.name(),
1447                        child.name(),
1448                        worker.batch_formats(),
1449                        child.batch_formats()
1450                    )));
1451                }
1452                Ok(worker)
1453            })
1454            .collect::<NpResult<Vec<_>>>()?;
1455        Ok(Box::new(NativeCompositeDecoderWorker {
1456            children,
1457            detector_ids: self.detector_ids.clone(),
1458            observable_ids: self.observable_ids.clone(),
1459            observable_indices: self.observable_indices.clone(),
1460            child_plans: self.child_plans.clone(),
1461            batch_formats: self.batch_formats.clone(),
1462        }))
1463    }
1464}
1465
1466struct NativeCompositeDecoderWorker {
1467    children: Vec<Box<dyn NativeDecoderWorker>>,
1468    detector_ids: Vec<i64>,
1469    observable_ids: Vec<i64>,
1470    observable_indices: HashMap<i64, usize>,
1471    child_plans: Vec<CompositeChildPlan>,
1472    batch_formats: Vec<DetectorBatchFormat>,
1473}
1474
1475impl NativeCompositeDecoderWorker {
1476    fn validate_detector_order(&self, detector_ids: &[i64]) -> NpResult<()> {
1477        if detector_ids != self.detector_ids {
1478            return Err(NpError::new(
1479                "native composite decoder received detectors in an unexpected order",
1480            ));
1481        }
1482        Ok(())
1483    }
1484
1485    fn merge_packed_child(
1486        observable_ids: &[i64],
1487        observable_indices: &HashMap<i64, usize>,
1488        output: &mut [u8],
1489        child: &PackedObservableShotBatch,
1490    ) -> NpResult<()> {
1491        let output_byte_count = observable_ids.len().div_ceil(8);
1492        for shot in 0..child.shots {
1493            for (child_index, observable_id) in child.observable_ids.iter().enumerate() {
1494                if child.data[shot * child.observable_byte_count + (child_index >> 3)]
1495                    & (1 << (child_index & 7))
1496                    == 0
1497                {
1498                    continue;
1499                }
1500                let output_index = observable_indices.get(observable_id).ok_or_else(|| {
1501                    NpError::new(format!(
1502                        "native composite child returned unknown observable id {observable_id}"
1503                    ))
1504                })?;
1505                output[shot * output_byte_count + (output_index >> 3)] |= 1 << (output_index & 7);
1506            }
1507        }
1508        Ok(())
1509    }
1510
1511    fn project_batch(
1512        source: DetectorBatchView<'_>,
1513        plan: &CompositeChildPlan,
1514    ) -> NpResult<DetectorBatch> {
1515        match source {
1516            DetectorBatchView::Masks(view) => DetectorBatch::Masks {
1517                detector_ids: plan.detector_ids.clone(),
1518                masks: plan
1519                    .detector_indices
1520                    .iter()
1521                    .map(|index| view.masks[*index].clone())
1522                    .collect(),
1523                shots: view.shots,
1524            }
1525            .validated_shape(),
1526            DetectorBatchView::Packed(view) => {
1527                let child_byte_count = plan.detector_indices.len().div_ceil(8);
1528                let len = view.shots.checked_mul(child_byte_count).ok_or_else(|| {
1529                    NpError::new("composite packed detector projection length overflowed usize")
1530                })?;
1531                let mut data = vec![0u8; len];
1532                for shot in 0..view.shots {
1533                    for (child_detector, source_detector) in
1534                        plan.detector_indices.iter().copied().enumerate()
1535                    {
1536                        if view.data[shot * view.detector_byte_count + (source_detector >> 3)]
1537                            & (1u8 << (source_detector & 7))
1538                            != 0
1539                        {
1540                            data[shot * child_byte_count + (child_detector >> 3)] |=
1541                                1u8 << (child_detector & 7);
1542                        }
1543                    }
1544                }
1545                DetectorBatch::Packed {
1546                    detector_ids: plan.detector_ids.clone(),
1547                    data,
1548                    shots: view.shots,
1549                    detector_byte_count: child_byte_count,
1550                }
1551                .validated_shape()
1552            }
1553            DetectorBatchView::Events(view) => {
1554                let mut offsets = empty_detector_event_offsets(view.shots)?;
1555                let mut events = Vec::new();
1556                for shot in 0..view.shots {
1557                    for source_detector in &view.events[view.offsets[shot]..view.offsets[shot + 1]]
1558                    {
1559                        if let Some(child_detector) = plan.global_to_local[*source_detector] {
1560                            events.push(child_detector);
1561                        }
1562                    }
1563                    offsets.push(events.len());
1564                }
1565                DetectorBatch::Events {
1566                    detector_ids: plan.detector_ids.clone(),
1567                    offsets,
1568                    events,
1569                    shots: view.shots,
1570                }
1571                .validated_shape()
1572            }
1573        }
1574    }
1575}
1576
1577trait ValidatedDetectorBatch {
1578    fn validated_shape(self) -> NpResult<DetectorBatch>;
1579}
1580
1581impl ValidatedDetectorBatch for DetectorBatch {
1582    fn validated_shape(self) -> NpResult<DetectorBatch> {
1583        self.validate_shape()?;
1584        Ok(self)
1585    }
1586}
1587
1588impl NativeDecoderWorker for NativeCompositeDecoderWorker {
1589    fn name(&self) -> &str {
1590        "composite"
1591    }
1592
1593    fn detector_ids(&self) -> &[i64] {
1594        &self.detector_ids
1595    }
1596
1597    fn observable_ids(&self) -> &[i64] {
1598        &self.observable_ids
1599    }
1600
1601    fn batch_formats(&self) -> &[DetectorBatchFormat] {
1602        &self.batch_formats
1603    }
1604
1605    fn decode_batch(
1606        &mut self,
1607        detectors: DetectorBatchView<'_>,
1608    ) -> NpResult<DecoderCorrectionBatch> {
1609        self.validate_detector_order(detectors.detector_ids())?;
1610        detectors.validate_shape()?;
1611        let input_format = detectors.format();
1612        let shots = detectors.shots();
1613
1614        let child_targets = self
1615            .children
1616            .iter()
1617            .map(|child| {
1618                if child.batch_formats().contains(&input_format) {
1619                    input_format
1620                } else {
1621                    child.batch_formats()[0]
1622                }
1623            })
1624            .collect::<Vec<_>>();
1625        let mut shared = Vec::<(DetectorBatchFormat, DetectorBatch)>::new();
1626        for target in child_targets.iter().copied() {
1627            if !shared.iter().any(|(format, _)| *format == target) {
1628                shared.push((
1629                    target,
1630                    convert_detector_batch_prevalidated(detectors, target)?,
1631                ));
1632            }
1633        }
1634
1635        let mut mask_output = (input_format == DetectorBatchFormat::Masks)
1636            .then(|| vec![Mask::zero(crate::word_count(shots)); self.observable_ids.len()]);
1637        let mut packed_output = (input_format != DetectorBatchFormat::Masks)
1638            .then(|| PackedObservableShotBatch::zero(self.observable_ids.clone(), shots))
1639            .transpose()?;
1640
1641        for (((child, plan), target), child_index) in self
1642            .children
1643            .iter_mut()
1644            .zip(&self.child_plans)
1645            .zip(child_targets)
1646            .zip(0usize..)
1647        {
1648            let source = shared
1649                .iter()
1650                .find_map(|(format, batch)| (*format == target).then(|| batch.view()))
1651                .expect("shared conversion exists for every child target");
1652            let child_batch = Self::project_batch(source, plan)?;
1653            let corrections = child
1654                .decode_batch_checked(child_batch.view())
1655                .map_err(|err| {
1656                    NpError::new(format!(
1657                        "composite decoder child {child_index} (`{}`) failed: {}",
1658                        child.name(),
1659                        err.message()
1660                    ))
1661                })?;
1662            if let Some(output) = &mut mask_output {
1663                let corrections = corrections.into_masks()?;
1664                for (observable_id, mask) in corrections
1665                    .observable_ids
1666                    .into_iter()
1667                    .zip(corrections.masks)
1668                {
1669                    let output_index =
1670                        self.observable_indices.get(&observable_id).ok_or_else(|| {
1671                            NpError::new(format!(
1672                            "native composite child returned unknown observable id {observable_id}"
1673                        ))
1674                        })?;
1675                    output[*output_index] = mask;
1676                }
1677            } else if let Some(output) = &mut packed_output {
1678                let corrections = corrections.into_packed()?;
1679                Self::merge_packed_child(
1680                    &self.observable_ids,
1681                    &self.observable_indices,
1682                    &mut output.data,
1683                    &corrections,
1684                )?;
1685            }
1686        }
1687
1688        if let Some(masks) = mask_output {
1689            Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
1690                self.observable_ids.clone(),
1691                masks,
1692                shots,
1693            )?))
1694        } else {
1695            Ok(DecoderCorrectionBatch::Packed(
1696                packed_output.expect("non-mask inputs allocate packed output"),
1697            ))
1698        }
1699    }
1700}
1701
1702#[derive(Debug, Clone, PartialEq)]
1703pub struct NativeNoCorrectionDecoder {
1704    detector_ids: Vec<i64>,
1705    observable_ids: Vec<i64>,
1706}
1707
1708impl NativeNoCorrectionDecoder {
1709    pub fn new(observable_ids: Vec<i64>) -> Self {
1710        Self {
1711            detector_ids: Vec::new(),
1712            observable_ids,
1713        }
1714    }
1715
1716    pub fn with_detector_ids(detector_ids: Vec<i64>, observable_ids: Vec<i64>) -> NpResult<Self> {
1717        validate_decoder_detector_ids(&detector_ids)?;
1718        Ok(Self {
1719            detector_ids,
1720            observable_ids,
1721        })
1722    }
1723}
1724
1725impl NativeDecoderFactory for NativeNoCorrectionDecoder {
1726    fn name(&self) -> &str {
1727        "no-correction"
1728    }
1729
1730    fn detector_ids(&self) -> &[i64] {
1731        &self.detector_ids
1732    }
1733
1734    fn observable_ids(&self) -> &[i64] {
1735        &self.observable_ids
1736    }
1737
1738    fn batch_formats(&self) -> &[DetectorBatchFormat] {
1739        &ALL_BATCH_FORMATS
1740    }
1741
1742    fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
1743        Ok(Box::new(NativeNoCorrectionDecoderWorker {
1744            detector_ids: self.detector_ids.clone(),
1745            observable_ids: self.observable_ids.clone(),
1746        }))
1747    }
1748}
1749
1750#[derive(Debug)]
1751struct NativeNoCorrectionDecoderWorker {
1752    detector_ids: Vec<i64>,
1753    observable_ids: Vec<i64>,
1754}
1755
1756impl NativeDecoderWorker for NativeNoCorrectionDecoderWorker {
1757    fn name(&self) -> &str {
1758        "no-correction"
1759    }
1760
1761    fn detector_ids(&self) -> &[i64] {
1762        &self.detector_ids
1763    }
1764
1765    fn observable_ids(&self) -> &[i64] {
1766        &self.observable_ids
1767    }
1768
1769    fn batch_formats(&self) -> &[DetectorBatchFormat] {
1770        &ALL_BATCH_FORMATS
1771    }
1772
1773    fn decode_batch(
1774        &mut self,
1775        detectors: DetectorBatchView<'_>,
1776    ) -> NpResult<DecoderCorrectionBatch> {
1777        match detectors {
1778            DetectorBatchView::Masks(view) => {
1779                Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
1780                    self.observable_ids.clone(),
1781                    vec![Mask::zero(crate::word_count(view.shots)); self.observable_ids.len()],
1782                    view.shots,
1783                )?))
1784            }
1785            DetectorBatchView::Packed(view) => Ok(DecoderCorrectionBatch::Packed(
1786                PackedObservableShotBatch::zero(self.observable_ids.clone(), view.shots)?,
1787            )),
1788            DetectorBatchView::Events(view) => Ok(DecoderCorrectionBatch::Packed(
1789                PackedObservableShotBatch::zero(self.observable_ids.clone(), view.shots)?,
1790            )),
1791        }
1792    }
1793}
1794
1795#[derive(Debug, Clone, PartialEq)]
1796pub struct NativeGraphlikeDetectorCopyDecoder {
1797    detector_ids: Vec<i64>,
1798    observable_ids: Vec<i64>,
1799    observable_detector_indices: Vec<Option<usize>>,
1800}
1801
1802impl NativeGraphlikeDetectorCopyDecoder {
1803    pub fn from_graphlike_problem(problem: GraphlikeDecodingProblem) -> NpResult<Self> {
1804        let detector_count = problem.detector_ids().len();
1805        let observable_count = problem.observable_ids().len();
1806        let mut observable_detector_indices = vec![None; observable_count];
1807        for edge in problem.iter_edges() {
1808            if edge.detector_count() != 1 || edge.fault_observables().len() != 1 {
1809                continue;
1810            }
1811            let detector_index = edge
1812                .detectors()
1813                .next()
1814                .expect("single-detector edge has one detector");
1815            let observable_index = edge
1816                .fault_observables()
1817                .next()
1818                .expect("single-observable edge has one observable");
1819            if detector_index >= detector_count {
1820                return Err(NpError::new(format!(
1821                    "graphlike-detector-copy edge {} references detector index {} but only {} detectors exist",
1822                    edge.dem_edge_index(),
1823                    detector_index,
1824                    detector_count
1825                )));
1826            }
1827            if observable_index >= observable_count {
1828                return Err(NpError::new(format!(
1829                    "graphlike-detector-copy edge {} references observable index {} but only {} observables exist",
1830                    edge.dem_edge_index(),
1831                    observable_index,
1832                    observable_count
1833                )));
1834            }
1835            if let Some(existing_detector_index) = observable_detector_indices[observable_index] {
1836                return Err(NpError::new(format!(
1837                    "graphlike-detector-copy found multiple single-detector candidate edges for observable id {}; detector indices {} and {}",
1838                    problem.observable_ids()[observable_index],
1839                    existing_detector_index,
1840                    detector_index
1841                )));
1842            }
1843            observable_detector_indices[observable_index] = Some(detector_index);
1844        }
1845        let (detector_ids, observable_ids) = problem.into_ids();
1846        Ok(Self {
1847            detector_ids,
1848            observable_ids,
1849            observable_detector_indices,
1850        })
1851    }
1852
1853    pub fn observable_detector_indices(&self) -> &[Option<usize>] {
1854        &self.observable_detector_indices
1855    }
1856}
1857
1858impl NativeDecoderFactory for NativeGraphlikeDetectorCopyDecoder {
1859    fn name(&self) -> &str {
1860        "graphlike-detector-copy"
1861    }
1862
1863    fn detector_ids(&self) -> &[i64] {
1864        &self.detector_ids
1865    }
1866
1867    fn observable_ids(&self) -> &[i64] {
1868        &self.observable_ids
1869    }
1870
1871    fn batch_formats(&self) -> &[DetectorBatchFormat] {
1872        &MASKS_BATCH_FORMATS
1873    }
1874
1875    fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
1876        Ok(Box::new(NativeGraphlikeDetectorCopyDecoderWorker {
1877            detector_ids: self.detector_ids.clone(),
1878            observable_ids: self.observable_ids.clone(),
1879            observable_detector_indices: self.observable_detector_indices.clone(),
1880        }))
1881    }
1882}
1883
1884#[derive(Debug)]
1885struct NativeGraphlikeDetectorCopyDecoderWorker {
1886    detector_ids: Vec<i64>,
1887    observable_ids: Vec<i64>,
1888    observable_detector_indices: Vec<Option<usize>>,
1889}
1890
1891impl NativeDecoderWorker for NativeGraphlikeDetectorCopyDecoderWorker {
1892    fn name(&self) -> &str {
1893        "graphlike-detector-copy"
1894    }
1895
1896    fn detector_ids(&self) -> &[i64] {
1897        &self.detector_ids
1898    }
1899
1900    fn observable_ids(&self) -> &[i64] {
1901        &self.observable_ids
1902    }
1903
1904    fn batch_formats(&self) -> &[DetectorBatchFormat] {
1905        &MASKS_BATCH_FORMATS
1906    }
1907
1908    fn decode_batch(
1909        &mut self,
1910        detectors: DetectorBatchView<'_>,
1911    ) -> NpResult<DecoderCorrectionBatch> {
1912        let DetectorBatchView::Masks(detectors) = detectors else {
1913            return Err(NpError::new(
1914                "graphlike-detector-copy only accepts Masks detector batches",
1915            ));
1916        };
1917        if detectors.detector_ids != self.detector_ids.as_slice() {
1918            return Err(NpError::new(
1919                "graphlike-detector-copy received detector masks in an unexpected order",
1920            ));
1921        }
1922        let words = crate::word_count(detectors.shots);
1923        let masks = self
1924            .observable_detector_indices
1925            .iter()
1926            .map(|detector_index| match detector_index {
1927                Some(detector_index) => detectors
1928                    .masks
1929                    .get(*detector_index)
1930                    .cloned()
1931                    .ok_or_else(|| {
1932                        NpError::new(format!(
1933                            "graphlike-detector-copy missing detector mask at index {detector_index}"
1934                        ))
1935                    }),
1936                None => Ok(Mask::zero(words)),
1937            })
1938            .collect::<NpResult<Vec<_>>>()?;
1939        Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
1940            self.observable_ids.clone(),
1941            masks,
1942            detectors.shots,
1943        )?))
1944    }
1945}
1946
1947#[cfg(feature = "decoder-fusion-blossom")]
1948#[derive(Debug, Clone, PartialEq)]
1949pub struct NativeFusionBlossomDecoder {
1950    detector_ids: Vec<i64>,
1951    observable_ids: Vec<i64>,
1952    edge_count: usize,
1953}
1954
1955#[cfg(feature = "decoder-fusion-blossom")]
1956impl NativeFusionBlossomDecoder {
1957    pub fn from_graphlike_problem(problem: GraphlikeDecodingProblem) -> NpResult<Self> {
1958        let edge_count = problem.edge_count();
1959        let (detector_ids, observable_ids) = problem.into_ids();
1960        Ok(Self {
1961            detector_ids,
1962            observable_ids,
1963            edge_count,
1964        })
1965    }
1966
1967    pub fn edge_count(&self) -> usize {
1968        self.edge_count
1969    }
1970
1971    fn unavailable_error() -> NpError {
1972        NpError::new(
1973            "fusion-blossom native backend scaffold is compiled, but no stable Rust dependency is linked yet",
1974        )
1975    }
1976}
1977
1978#[cfg(feature = "decoder-fusion-blossom")]
1979impl NativeDecoderFactory for NativeFusionBlossomDecoder {
1980    fn name(&self) -> &str {
1981        "fusion-blossom"
1982    }
1983
1984    fn detector_ids(&self) -> &[i64] {
1985        &self.detector_ids
1986    }
1987
1988    fn observable_ids(&self) -> &[i64] {
1989        &self.observable_ids
1990    }
1991
1992    fn batch_formats(&self) -> &[DetectorBatchFormat] {
1993        &PACKED_BATCH_FORMATS
1994    }
1995
1996    fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
1997        Ok(Box::new(NativeFusionBlossomDecoderWorker {
1998            detector_ids: self.detector_ids.clone(),
1999            observable_ids: self.observable_ids.clone(),
2000        }))
2001    }
2002}
2003
2004#[cfg(feature = "decoder-fusion-blossom")]
2005#[derive(Debug)]
2006struct NativeFusionBlossomDecoderWorker {
2007    detector_ids: Vec<i64>,
2008    observable_ids: Vec<i64>,
2009}
2010
2011#[cfg(feature = "decoder-fusion-blossom")]
2012impl NativeDecoderWorker for NativeFusionBlossomDecoderWorker {
2013    fn name(&self) -> &str {
2014        "fusion-blossom"
2015    }
2016
2017    fn detector_ids(&self) -> &[i64] {
2018        &self.detector_ids
2019    }
2020
2021    fn observable_ids(&self) -> &[i64] {
2022        &self.observable_ids
2023    }
2024
2025    fn batch_formats(&self) -> &[DetectorBatchFormat] {
2026        &PACKED_BATCH_FORMATS
2027    }
2028
2029    fn decode_batch(
2030        &mut self,
2031        _detectors: DetectorBatchView<'_>,
2032    ) -> NpResult<DecoderCorrectionBatch> {
2033        Err(NativeFusionBlossomDecoder::unavailable_error())
2034    }
2035}
2036
2037pub fn logical_residual_loss_mask_native(
2038    observables: &HashMap<i64, Mask>,
2039    corrections: &CorrectionMaskBatch,
2040    observable_ids: &[i64],
2041    all_mask: &Mask,
2042) -> Mask {
2043    let mut ids = observable_ids.to_vec();
2044    for observable_id in observables.keys() {
2045        if !ids.contains(observable_id) {
2046            ids.push(*observable_id);
2047        }
2048    }
2049    for observable_id in &corrections.observable_ids {
2050        if !ids.contains(observable_id) {
2051            ids.push(*observable_id);
2052        }
2053    }
2054
2055    let mut loss = Mask::zero(all_mask.words.len());
2056    let zero = Mask::zero(all_mask.words.len());
2057    for observable_id in ids {
2058        let observable = observables.get(&observable_id).unwrap_or(&zero);
2059        let correction = corrections.get(observable_id).unwrap_or(&zero);
2060        let mut residual = observable.clone();
2061        residual.xor_assign(correction);
2062        loss.or_assign(&residual);
2063    }
2064    loss.and_assign(all_mask);
2065    loss
2066}
2067
2068#[cfg(test)]
2069mod tests {
2070    use super::*;
2071    use crate::GraphlikeEdge;
2072    use std::sync::Arc;
2073
2074    struct FixedCorrectionDecoder {
2075        detector_ids: Vec<i64>,
2076        observable_ids: Vec<i64>,
2077        correction: Mask,
2078    }
2079
2080    struct FixedCorrectionDecoderWorker {
2081        detector_ids: Vec<i64>,
2082        observable_ids: Vec<i64>,
2083        correction: Mask,
2084    }
2085
2086    struct FastCopyDecoder {
2087        detector_ids: Vec<i64>,
2088        observable_ids: Vec<i64>,
2089    }
2090
2091    struct FastCopyDecoderWorker {
2092        detector_ids: Vec<i64>,
2093        observable_ids: Vec<i64>,
2094    }
2095
2096    struct SingleFormatCopyDecoder {
2097        detector_ids: Vec<i64>,
2098        observable_ids: Vec<i64>,
2099        formats: Vec<DetectorBatchFormat>,
2100    }
2101
2102    struct SingleFormatCopyDecoderWorker {
2103        detector_ids: Vec<i64>,
2104        observable_ids: Vec<i64>,
2105        formats: Vec<DetectorBatchFormat>,
2106    }
2107
2108    fn graphlike_edges() -> Vec<GraphlikeEdge> {
2109        vec![
2110            GraphlikeEdge {
2111                detectors: vec![1],
2112                fault_observables: vec![0],
2113                probability: 0.1,
2114                dem_edge_index: 0,
2115            },
2116            GraphlikeEdge {
2117                detectors: vec![0, 1],
2118                fault_observables: vec![1],
2119                probability: 0.2,
2120                dem_edge_index: 1,
2121            },
2122        ]
2123    }
2124
2125    fn graphlike_problem() -> GraphlikeDecodingProblem {
2126        GraphlikeDecodingProblem::new(
2127            vec![10, 20],
2128            vec![Vec::new(), Vec::new()],
2129            vec![0, 1],
2130            graphlike_edges(),
2131        )
2132        .unwrap()
2133    }
2134
2135    #[test]
2136    fn packed_residual_count_uses_the_canonical_layout_path() {
2137        let empty_corrections = PackedObservableShotBatch::zero(vec![], 3).unwrap();
2138        assert_eq!(
2139            packed_residual_failure_count(&[], &[], 0, &empty_corrections, 3).unwrap(),
2140            0
2141        );
2142
2143        let corrections =
2144            PackedObservableShotBatch::new(vec![10, 20], vec![0b00, 0b01, 0b00, 0b01], 4).unwrap();
2145
2146        let failures =
2147            packed_residual_failure_count(&[10, 20], &[0b00, 0b01, 0b10, 0b11], 1, &corrections, 4)
2148                .unwrap();
2149
2150        assert_eq!(failures, 2);
2151    }
2152
2153    #[test]
2154    fn packed_residual_count_rejects_noncanonical_layouts() {
2155        let reordered =
2156            PackedObservableShotBatch::new(vec![20, 10], vec![0b10, 0b01, 0b11], 3).unwrap();
2157        let err = packed_residual_failure_count(&[10, 20], &[0b01, 0b10, 0b11], 1, &reordered, 3)
2158            .unwrap_err();
2159        assert!(err.to_string().contains("observable layout mismatch"));
2160
2161        for ids in [vec![10], vec![10, 20, 30], vec![20, 30]] {
2162            let corrections = PackedObservableShotBatch::zero(ids, 1).unwrap();
2163            let err =
2164                packed_residual_failure_count(&[10, 20], &[0], 1, &corrections, 1).unwrap_err();
2165            assert!(err.to_string().contains("observable layout mismatch"));
2166        }
2167    }
2168
2169    #[test]
2170    fn packed_observable_batches_require_zero_padding() {
2171        for (ids, data) in [
2172            (vec![0], vec![0b1000_0000]),
2173            ((0..7).collect(), vec![0b1000_0000]),
2174            ((0..9).collect(), vec![0, 0b0000_0010]),
2175        ] {
2176            let err = PackedObservableShotBatch::new(ids, data, 1).unwrap_err();
2177            assert!(err.to_string().contains("non-zero padding bits"));
2178        }
2179
2180        assert!(PackedObservableShotBatch::new((0..8).collect(), vec![0xff], 1).is_ok());
2181        assert!(
2182            PackedObservableShotBatch::new((0..9).collect(), vec![0xff, 0b0000_0001], 1,).is_ok()
2183        );
2184
2185        let corrections = PackedObservableShotBatch::zero(vec![0], 1).unwrap();
2186        let err =
2187            packed_residual_failure_count(&[0], &[0b1000_0000], 1, &corrections, 1).unwrap_err();
2188        assert!(err
2189            .to_string()
2190            .contains("packed observable batch shot 0 has non-zero padding bits"));
2191    }
2192
2193    #[test]
2194    fn packed_residual_count_rejects_malformed_rows() {
2195        let corrections = PackedObservableShotBatch::zero(vec![10], 1).unwrap();
2196
2197        let err = packed_residual_failure_count(&[10], &[], 0, &corrections, 1).unwrap_err();
2198
2199        assert!(err.to_string().contains("observable byte count"));
2200    }
2201
2202    fn patterned_detector_masks(detector_count: usize, shots: usize) -> Vec<Mask> {
2203        let mut masks = vec![Mask::zero(crate::word_count(shots)); detector_count];
2204        for (detector, mask) in masks.iter_mut().enumerate() {
2205            for shot in 0..shots {
2206                if (shot * 5 + detector * 3 + 1) % 7 < 3 {
2207                    mask.words[shot >> 6] |= 1u64 << (shot & 63);
2208                }
2209            }
2210        }
2211        masks
2212    }
2213
2214    #[test]
2215    fn detector_formats_round_trip_across_byte_and_word_boundaries() {
2216        let detector_ids = (100..109).collect::<Vec<_>>();
2217        for shots in [0, 1, 7, 8, 63, 64, 65, 129] {
2218            let expected = patterned_detector_masks(detector_ids.len(), shots);
2219            let source = DetectorMaskBatchView::new(&detector_ids, &expected, shots).unwrap();
2220            for first_format in DetectorBatchFormat::STABLE_ORDER {
2221                let first = convert_detector_batch(source.into(), first_format).unwrap();
2222                assert_eq!(first.format(), first_format);
2223                for second_format in DetectorBatchFormat::STABLE_ORDER {
2224                    let second = convert_detector_batch(first.view(), second_format).unwrap();
2225                    let round_trip =
2226                        convert_detector_batch(second.view(), DetectorBatchFormat::Masks).unwrap();
2227                    let DetectorBatch::Masks {
2228                        detector_ids: actual_ids,
2229                        masks: actual_masks,
2230                        shots: actual_shots,
2231                    } = round_trip
2232                    else {
2233                        unreachable!()
2234                    };
2235                    assert_eq!(actual_ids, detector_ids);
2236                    assert_eq!(actual_masks, expected);
2237                    assert_eq!(actual_shots, shots);
2238                }
2239            }
2240        }
2241    }
2242
2243    #[test]
2244    fn detector_events_combine_duplicates_by_gf2_xor_and_canonicalize_output() {
2245        let detector_ids = [10, 20, 30];
2246        let offsets = [0, 4, 7, 7];
2247        let events = [0, 0, 1, 2, 1, 1, 1];
2248        let source = DetectorEventShotBatchView::new(&detector_ids, &offsets, &events, 3).unwrap();
2249
2250        let masks = convert_detector_batch(source.into(), DetectorBatchFormat::Masks).unwrap();
2251        let DetectorBatch::Masks { masks, .. } = masks else {
2252            unreachable!()
2253        };
2254        assert_eq!(masks[0].words, [0]);
2255        assert_eq!(masks[1].words, [0b011]);
2256        assert_eq!(masks[2].words, [0b001]);
2257
2258        let packed = convert_detector_batch(source.into(), DetectorBatchFormat::Packed).unwrap();
2259        let DetectorBatch::Packed { data, .. } = packed else {
2260            unreachable!()
2261        };
2262        assert_eq!(data, [0b110, 0b010, 0]);
2263
2264        let canonical = convert_detector_batch(source.into(), DetectorBatchFormat::Events).unwrap();
2265        let DetectorBatch::Events {
2266            offsets, events, ..
2267        } = canonical
2268        else {
2269            unreachable!()
2270        };
2271        assert_eq!(offsets, [0, 2, 3, 3]);
2272        assert_eq!(events, [1, 2, 1]);
2273    }
2274
2275    #[test]
2276    fn detector_event_offset_allocation_overflow_returns_an_error() {
2277        let masks = DetectorMaskBatchView::new(&[], &[], usize::MAX).unwrap();
2278        let error = convert_detector_batch(masks.into(), DetectorBatchFormat::Events).unwrap_err();
2279        assert_eq!(
2280            error.message(),
2281            "detector event offset length overflowed usize"
2282        );
2283
2284        let packed = PackedDetectorShotBatchView::new(&[], &[], usize::MAX - 1).unwrap();
2285        let error = convert_detector_batch(packed.into(), DetectorBatchFormat::Events).unwrap_err();
2286        assert!(error
2287            .message()
2288            .contains("detector event offset storage for"));
2289        assert!(error.message().contains("could not be allocated"));
2290    }
2291
2292    #[test]
2293    fn packed_zero_and_no_correction_report_length_overflow() {
2294        let observable_ids = (0..9).collect::<Vec<_>>();
2295        let error =
2296            PackedObservableShotBatch::zero(observable_ids.clone(), usize::MAX).unwrap_err();
2297        assert_eq!(
2298            error.message(),
2299            "packed correction byte length overflowed usize"
2300        );
2301
2302        let factory = NativeNoCorrectionDecoder::new(observable_ids);
2303        let mut worker = factory.create_worker().unwrap();
2304        let packed = PackedDetectorShotBatchView::new(&[], &[], usize::MAX).unwrap();
2305        let error = worker.decode_batch_checked(packed.into()).unwrap_err();
2306        assert_eq!(
2307            error.message(),
2308            "packed correction byte length overflowed usize"
2309        );
2310
2311        let events = DetectorEventShotBatchView {
2312            detector_ids: &[],
2313            offsets: &[],
2314            events: &[],
2315            shots: usize::MAX,
2316        };
2317        let error = worker.decode_batch(events.into()).unwrap_err();
2318        assert_eq!(
2319            error.message(),
2320            "packed correction byte length overflowed usize"
2321        );
2322
2323        let child: Arc<dyn NativeDecoderFactory> =
2324            Arc::new(NativeNoCorrectionDecoder::new(vec![0]));
2325        let factory = NativeCompositeDecoder::new(vec![child]).unwrap();
2326        let mut worker = factory.create_worker().unwrap();
2327        let capacity_overflow_shots = (isize::MAX as usize).checked_add(1).unwrap();
2328        let packed = PackedDetectorShotBatchView::new(&[], &[], capacity_overflow_shots).unwrap();
2329        let error = worker.decode_batch_checked(packed.into()).unwrap_err();
2330        assert!(error.message().contains("packed correction storage for"));
2331        assert!(error.message().contains("could not be allocated"));
2332    }
2333
2334    #[test]
2335    fn public_detector_views_reject_duplicate_ids() {
2336        let ids = [7, 7];
2337        let masks = [Mask::zero(1), Mask::zero(1)];
2338        assert!(DetectorMaskBatchView::new(&ids, &masks, 1).is_err());
2339        assert!(PackedDetectorShotBatchView::new(&ids, &[0], 1).is_err());
2340        assert!(DetectorEventShotBatchView::new(&ids, &[0, 0], &[], 1).is_err());
2341    }
2342
2343    #[test]
2344    fn checked_dispatch_trusts_prevalidated_detector_id_metadata() {
2345        struct TrustedMetadataWorker {
2346            calls: usize,
2347        }
2348
2349        impl NativeDecoderWorker for TrustedMetadataWorker {
2350            fn name(&self) -> &str {
2351                "trusted-metadata"
2352            }
2353
2354            fn detector_ids(&self) -> &[i64] {
2355                &[7, 7]
2356            }
2357
2358            fn observable_ids(&self) -> &[i64] {
2359                &[]
2360            }
2361
2362            fn batch_formats(&self) -> &[DetectorBatchFormat] {
2363                &MASKS_BATCH_FORMATS
2364            }
2365
2366            fn decode_batch(
2367                &mut self,
2368                detectors: DetectorBatchView<'_>,
2369            ) -> NpResult<DecoderCorrectionBatch> {
2370                self.calls += 1;
2371                Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::empty(
2372                    detectors.shots(),
2373                )))
2374            }
2375        }
2376
2377        let ids = [7, 7];
2378        let masks = [Mask::zero(1), Mask::zero(1)];
2379        let raw_view = DetectorMaskBatchView {
2380            detector_ids: &ids,
2381            masks: &masks,
2382            shots: 1,
2383        };
2384        let mut worker = TrustedMetadataWorker { calls: 0 };
2385
2386        worker.decode_batch_checked(raw_view.into()).unwrap();
2387        worker.decode_batch_checked(raw_view.into()).unwrap();
2388
2389        assert_eq!(worker.calls, 2);
2390    }
2391
2392    #[test]
2393    fn decoder_format_metadata_and_selection_are_strict_and_ordered() {
2394        assert!(validate_decoder_batch_formats(&[]).is_err());
2395        assert!(validate_decoder_batch_formats(&[
2396            DetectorBatchFormat::Packed,
2397            DetectorBatchFormat::Packed,
2398        ])
2399        .is_err());
2400        assert_eq!(
2401            select_detector_batch_format(
2402                &[DetectorBatchFormat::Events, DetectorBatchFormat::Packed],
2403                &[DetectorBatchFormat::Masks, DetectorBatchFormat::Packed],
2404            )
2405            .unwrap(),
2406            DetectorBatchFormat::Packed
2407        );
2408        assert_eq!(
2409            select_detector_batch_format(
2410                &[DetectorBatchFormat::Events, DetectorBatchFormat::Packed],
2411                &[DetectorBatchFormat::Masks],
2412            )
2413            .unwrap(),
2414            DetectorBatchFormat::Events
2415        );
2416    }
2417
2418    #[test]
2419    fn checked_decode_enforces_the_fixed_input_to_correction_mapping() {
2420        struct WrongVariantWorker;
2421
2422        impl NativeDecoderWorker for WrongVariantWorker {
2423            fn name(&self) -> &str {
2424                "wrong-variant"
2425            }
2426
2427            fn detector_ids(&self) -> &[i64] {
2428                &[]
2429            }
2430
2431            fn observable_ids(&self) -> &[i64] {
2432                &[]
2433            }
2434
2435            fn batch_formats(&self) -> &[DetectorBatchFormat] {
2436                &ALL_BATCH_FORMATS
2437            }
2438
2439            fn decode_batch(
2440                &mut self,
2441                detectors: DetectorBatchView<'_>,
2442            ) -> NpResult<DecoderCorrectionBatch> {
2443                match detectors {
2444                    DetectorBatchView::Masks(view) => Ok(DecoderCorrectionBatch::Packed(
2445                        PackedObservableShotBatch::zero(vec![], view.shots)?,
2446                    )),
2447                    DetectorBatchView::Packed(view) => Ok(DecoderCorrectionBatch::Masks(
2448                        CorrectionMaskBatch::empty(view.shots),
2449                    )),
2450                    DetectorBatchView::Events(view) => Ok(DecoderCorrectionBatch::Masks(
2451                        CorrectionMaskBatch::empty(view.shots),
2452                    )),
2453                }
2454            }
2455        }
2456
2457        let mut worker = WrongVariantWorker;
2458        let masks = DetectorMaskBatchView::new(&[], &[], 1).unwrap();
2459        let packed = PackedDetectorShotBatchView::new(&[], &[], 1).unwrap();
2460        let offsets = [0, 0];
2461        let events = DetectorEventShotBatchView::new(&[], &offsets, &[], 1).unwrap();
2462        for input in [masks.into(), packed.into(), events.into()] {
2463            let error = worker.decode_batch_checked(input).unwrap_err();
2464            assert!(error.message().contains("expected"));
2465            assert!(error.message().contains("corrections"));
2466        }
2467    }
2468
2469    impl NativeDecoderFactory for FixedCorrectionDecoder {
2470        fn name(&self) -> &str {
2471            "fixed-correction"
2472        }
2473
2474        fn detector_ids(&self) -> &[i64] {
2475            &self.detector_ids
2476        }
2477
2478        fn observable_ids(&self) -> &[i64] {
2479            &self.observable_ids
2480        }
2481
2482        fn batch_formats(&self) -> &[DetectorBatchFormat] {
2483            &MASKS_BATCH_FORMATS
2484        }
2485
2486        fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
2487            Ok(Box::new(FixedCorrectionDecoderWorker {
2488                detector_ids: self.detector_ids.clone(),
2489                observable_ids: self.observable_ids.clone(),
2490                correction: self.correction.clone(),
2491            }))
2492        }
2493    }
2494
2495    impl NativeDecoderWorker for FixedCorrectionDecoderWorker {
2496        fn name(&self) -> &str {
2497            "fixed-correction"
2498        }
2499
2500        fn detector_ids(&self) -> &[i64] {
2501            &self.detector_ids
2502        }
2503
2504        fn observable_ids(&self) -> &[i64] {
2505            &self.observable_ids
2506        }
2507
2508        fn batch_formats(&self) -> &[DetectorBatchFormat] {
2509            &MASKS_BATCH_FORMATS
2510        }
2511
2512        fn decode_batch(
2513            &mut self,
2514            detectors: DetectorBatchView<'_>,
2515        ) -> NpResult<DecoderCorrectionBatch> {
2516            let DetectorBatchView::Masks(detectors) = detectors else {
2517                return Err(NpError::new("fixed-correction only accepts Masks"));
2518            };
2519            Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
2520                self.observable_ids.clone(),
2521                vec![self.correction.clone()],
2522                detectors.shots,
2523            )?))
2524        }
2525    }
2526
2527    impl NativeDecoderFactory for FastCopyDecoder {
2528        fn name(&self) -> &str {
2529            "fast-copy"
2530        }
2531
2532        fn detector_ids(&self) -> &[i64] {
2533            &self.detector_ids
2534        }
2535
2536        fn observable_ids(&self) -> &[i64] {
2537            &self.observable_ids
2538        }
2539
2540        fn batch_formats(&self) -> &[DetectorBatchFormat] {
2541            &ALL_BATCH_FORMATS
2542        }
2543
2544        fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
2545            Ok(Box::new(FastCopyDecoderWorker {
2546                detector_ids: self.detector_ids.clone(),
2547                observable_ids: self.observable_ids.clone(),
2548            }))
2549        }
2550    }
2551
2552    impl NativeDecoderWorker for FastCopyDecoderWorker {
2553        fn name(&self) -> &str {
2554            "fast-copy"
2555        }
2556
2557        fn detector_ids(&self) -> &[i64] {
2558            &self.detector_ids
2559        }
2560
2561        fn observable_ids(&self) -> &[i64] {
2562            &self.observable_ids
2563        }
2564
2565        fn batch_formats(&self) -> &[DetectorBatchFormat] {
2566            &ALL_BATCH_FORMATS
2567        }
2568
2569        fn decode_batch(
2570            &mut self,
2571            detectors: DetectorBatchView<'_>,
2572        ) -> NpResult<DecoderCorrectionBatch> {
2573            match detectors {
2574                DetectorBatchView::Masks(detectors) => {
2575                    Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
2576                        self.observable_ids.clone(),
2577                        vec![detectors.masks[0].clone()],
2578                        detectors.shots,
2579                    )?))
2580                }
2581                DetectorBatchView::Packed(detectors) => {
2582                    let data = (0..detectors.shots)
2583                        .map(|shot| detectors.data[shot * detectors.detector_byte_count] & 1)
2584                        .collect();
2585                    Ok(DecoderCorrectionBatch::Packed(
2586                        PackedObservableShotBatch::new(
2587                            self.observable_ids.clone(),
2588                            data,
2589                            detectors.shots,
2590                        )?,
2591                    ))
2592                }
2593                DetectorBatchView::Events(detectors) => {
2594                    let data = (0..detectors.shots)
2595                        .map(|shot| {
2596                            (detectors.events[detectors.offsets[shot]..detectors.offsets[shot + 1]]
2597                                .iter()
2598                                .filter(|&&event| event == 0)
2599                                .count()
2600                                & 1) as u8
2601                        })
2602                        .collect();
2603                    Ok(DecoderCorrectionBatch::Packed(
2604                        PackedObservableShotBatch::new(
2605                            self.observable_ids.clone(),
2606                            data,
2607                            detectors.shots,
2608                        )?,
2609                    ))
2610                }
2611            }
2612        }
2613    }
2614
2615    impl NativeDecoderFactory for SingleFormatCopyDecoder {
2616        fn name(&self) -> &str {
2617            "single-format-copy"
2618        }
2619
2620        fn detector_ids(&self) -> &[i64] {
2621            &self.detector_ids
2622        }
2623
2624        fn observable_ids(&self) -> &[i64] {
2625            &self.observable_ids
2626        }
2627
2628        fn batch_formats(&self) -> &[DetectorBatchFormat] {
2629            &self.formats
2630        }
2631
2632        fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
2633            Ok(Box::new(SingleFormatCopyDecoderWorker {
2634                detector_ids: self.detector_ids.clone(),
2635                observable_ids: self.observable_ids.clone(),
2636                formats: self.formats.clone(),
2637            }))
2638        }
2639    }
2640
2641    impl NativeDecoderWorker for SingleFormatCopyDecoderWorker {
2642        fn name(&self) -> &str {
2643            "single-format-copy"
2644        }
2645
2646        fn detector_ids(&self) -> &[i64] {
2647            &self.detector_ids
2648        }
2649
2650        fn observable_ids(&self) -> &[i64] {
2651            &self.observable_ids
2652        }
2653
2654        fn batch_formats(&self) -> &[DetectorBatchFormat] {
2655            &self.formats
2656        }
2657
2658        fn decode_batch(
2659            &mut self,
2660            detectors: DetectorBatchView<'_>,
2661        ) -> NpResult<DecoderCorrectionBatch> {
2662            let input_format = detectors.format();
2663            let shots = detectors.shots();
2664            let masks = convert_detector_batch(detectors, DetectorBatchFormat::Masks)?;
2665            let DetectorBatch::Masks { masks, .. } = masks else {
2666                unreachable!()
2667            };
2668            let corrections = CorrectionMaskBatch::new(
2669                self.observable_ids.clone(),
2670                vec![masks[0].clone()],
2671                shots,
2672            )?;
2673            if input_format == DetectorBatchFormat::Masks {
2674                Ok(DecoderCorrectionBatch::Masks(corrections))
2675            } else {
2676                Ok(DecoderCorrectionBatch::Packed(mask_corrections_to_packed(
2677                    corrections,
2678                )?))
2679            }
2680        }
2681    }
2682
2683    #[test]
2684    fn fixed_decoder_correction_controls_native_residual_loss() {
2685        let factory = FixedCorrectionDecoder {
2686            detector_ids: vec![],
2687            observable_ids: vec![0],
2688            correction: Mask {
2689                words: vec![0b0011],
2690            },
2691        };
2692        let mut decoder = factory.create_worker().unwrap();
2693        let detector_ids = vec![];
2694        let detector_masks = vec![];
2695        let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
2696        let corrections = decoder
2697            .decode_batch(view.into())
2698            .unwrap()
2699            .into_masks()
2700            .unwrap();
2701        let observables = HashMap::from([(
2702            0,
2703            Mask {
2704                words: vec![0b0110],
2705            },
2706        )]);
2707
2708        let loss =
2709            logical_residual_loss_mask_native(&observables, &corrections, &[0], &Mask::all(4));
2710
2711        assert_eq!(
2712            loss,
2713            Mask {
2714                words: vec![0b0101]
2715            }
2716        );
2717    }
2718
2719    #[test]
2720    fn composite_decoder_builds_stable_unions_and_merges_corrections() {
2721        let first: Arc<dyn NativeDecoderFactory> = Arc::new(FixedCorrectionDecoder {
2722            detector_ids: vec![10, 20],
2723            observable_ids: vec![2],
2724            correction: Mask {
2725                words: vec![0b0011],
2726            },
2727        });
2728        let second: Arc<dyn NativeDecoderFactory> = Arc::new(FixedCorrectionDecoder {
2729            detector_ids: vec![20, 30],
2730            observable_ids: vec![5],
2731            correction: Mask {
2732                words: vec![0b1100],
2733            },
2734        });
2735        let factory = NativeCompositeDecoder::new(vec![first, second]).unwrap();
2736        let mut decoder = factory.create_worker().unwrap();
2737        let detector_masks = vec![Mask::zero(1); 3];
2738        let detector_ids = decoder.detector_ids().to_vec();
2739        let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
2740
2741        let corrections = decoder
2742            .decode_batch_checked(view.into())
2743            .unwrap()
2744            .into_masks()
2745            .unwrap();
2746
2747        assert_eq!(factory.detector_ids(), &[10, 20, 30]);
2748        assert_eq!(factory.observable_ids(), &[2, 5]);
2749        assert_eq!(
2750            corrections.masks,
2751            vec![
2752                Mask {
2753                    words: vec![0b0011]
2754                },
2755                Mask {
2756                    words: vec![0b1100]
2757                }
2758            ]
2759        );
2760    }
2761
2762    #[test]
2763    fn composite_decoder_rejects_empty_and_duplicate_observables() {
2764        assert!(NativeCompositeDecoder::new(vec![]).is_err());
2765        let children: Vec<Arc<dyn NativeDecoderFactory>> = vec![
2766            Arc::new(NativeNoCorrectionDecoder::new(vec![1])),
2767            Arc::new(NativeNoCorrectionDecoder::new(vec![1])),
2768        ];
2769        let err = NativeCompositeDecoder::new(children).unwrap_err();
2770        assert!(err.to_string().contains("duplicate observable id 1"));
2771    }
2772
2773    #[test]
2774    fn composite_decoder_rejects_duplicate_child_detector_ids() {
2775        let child: Arc<dyn NativeDecoderFactory> = Arc::new(FixedCorrectionDecoder {
2776            detector_ids: vec![10, 10],
2777            observable_ids: vec![2],
2778            correction: Mask::zero(1),
2779        });
2780
2781        let error = NativeCompositeDecoder::new(vec![child]).unwrap_err();
2782
2783        assert_eq!(
2784            error.message(),
2785            "native composite decoder child 0 (`fixed-correction`) has invalid detector metadata: decoder detector ids must be unique; duplicate detector id 10"
2786        );
2787    }
2788
2789    #[test]
2790    fn composite_decoder_dispatches_packed_and_event_fast_paths() {
2791        let children: Vec<Arc<dyn NativeDecoderFactory>> = vec![
2792            Arc::new(FastCopyDecoder {
2793                detector_ids: vec![10],
2794                observable_ids: vec![2],
2795            }),
2796            Arc::new(FastCopyDecoder {
2797                detector_ids: vec![20],
2798                observable_ids: vec![5],
2799            }),
2800        ];
2801        let factory = NativeCompositeDecoder::new(children).unwrap();
2802        let mut decoder = factory.create_worker().unwrap();
2803        let packed_data = [0b01, 0b10, 0b11, 0b00];
2804        let detector_ids = decoder.detector_ids().to_vec();
2805        let packed_view = PackedDetectorShotBatchView::new(&detector_ids, &packed_data, 4).unwrap();
2806        let packed = decoder
2807            .decode_batch_checked(packed_view.into())
2808            .unwrap()
2809            .into_packed()
2810            .unwrap();
2811        assert_eq!(packed.observable_ids, vec![2, 5]);
2812        assert_eq!(packed.data, vec![0b01, 0b10, 0b11, 0b00]);
2813
2814        let offsets = [0, 1, 2, 4, 4];
2815        let events = [0, 1, 0, 1];
2816        let event_view =
2817            DetectorEventShotBatchView::new(&detector_ids, &offsets, &events, 4).unwrap();
2818        let event = decoder.decode_batch_checked(event_view.into()).unwrap();
2819        let event = event.into_packed().unwrap();
2820        assert_eq!(event.observable_ids, vec![2, 5]);
2821        assert_eq!(event.data, vec![0b01, 0b10, 0b11, 0b00]);
2822    }
2823
2824    #[test]
2825    fn heterogeneous_composite_ranks_formats_converts_once_and_merges() {
2826        let children: Vec<Arc<dyn NativeDecoderFactory>> = vec![
2827            Arc::new(SingleFormatCopyDecoder {
2828                detector_ids: vec![10],
2829                observable_ids: vec![2],
2830                formats: vec![DetectorBatchFormat::Masks],
2831            }),
2832            Arc::new(SingleFormatCopyDecoder {
2833                detector_ids: vec![20],
2834                observable_ids: vec![5],
2835                formats: vec![DetectorBatchFormat::Packed],
2836            }),
2837            Arc::new(SingleFormatCopyDecoder {
2838                detector_ids: vec![30],
2839                observable_ids: vec![7],
2840                formats: vec![DetectorBatchFormat::Events],
2841            }),
2842        ];
2843        let factory = NativeCompositeDecoder::new(children).unwrap();
2844        assert_eq!(factory.detector_ids(), [10, 20, 30]);
2845        assert_eq!(factory.observable_ids(), [2, 5, 7]);
2846        assert_eq!(factory.batch_formats(), DetectorBatchFormat::STABLE_ORDER);
2847        let mut worker = factory.create_worker().unwrap();
2848
2849        let offsets = [0, 1, 2, 3, 6];
2850        let events = [0, 1, 2, 0, 1, 2];
2851        let view =
2852            DetectorEventShotBatchView::new(factory.detector_ids(), &offsets, &events, 4).unwrap();
2853        let corrections = worker
2854            .decode_batch_checked(view.into())
2855            .unwrap()
2856            .into_packed()
2857            .unwrap();
2858
2859        assert_eq!(corrections.observable_ids, [2, 5, 7]);
2860        assert_eq!(corrections.data, [0b001, 0b010, 0b100, 0b111]);
2861    }
2862
2863    #[test]
2864    fn composite_decoder_reuses_scratch_across_batch_shapes() {
2865        let children: Vec<Arc<dyn NativeDecoderFactory>> = vec![
2866            Arc::new(FastCopyDecoder {
2867                detector_ids: vec![10],
2868                observable_ids: vec![2],
2869            }),
2870            Arc::new(FastCopyDecoder {
2871                detector_ids: vec![20],
2872                observable_ids: vec![5],
2873            }),
2874        ];
2875        let factory = NativeCompositeDecoder::new(children).unwrap();
2876        let mut decoder = factory.create_worker().unwrap();
2877        let detector_ids = decoder.detector_ids().to_vec();
2878
2879        for (shots, words) in [(4, vec![0b1010]), (65, vec![u64::MAX, 1])] {
2880            let first = Mask { words };
2881            let mut second = Mask::all(shots);
2882            second.xor_assign(&first);
2883            let masks = vec![first, second];
2884            let view = DetectorMaskBatchView::new(&detector_ids, &masks, shots).unwrap();
2885            let corrections = decoder
2886                .decode_batch_checked(view.into())
2887                .unwrap()
2888                .into_masks()
2889                .unwrap();
2890            assert_eq!(corrections.masks, masks);
2891        }
2892
2893        for data in [vec![0b01, 0b10, 0b11, 0b00], vec![0b11; 9]] {
2894            let view = PackedDetectorShotBatchView::new(&detector_ids, &data, data.len()).unwrap();
2895            let corrections = decoder
2896                .decode_batch_checked(view.into())
2897                .unwrap()
2898                .into_packed()
2899                .unwrap();
2900            assert_eq!(corrections.data, data);
2901        }
2902
2903        let offsets = [0, 2, 2, 3];
2904        let events = [0, 1, 1];
2905        let view = DetectorEventShotBatchView::new(&detector_ids, &offsets, &events, 3).unwrap();
2906        let corrections = decoder
2907            .decode_batch_checked(view.into())
2908            .unwrap()
2909            .into_packed()
2910            .unwrap();
2911        assert_eq!(corrections.data, vec![0b11, 0b00, 0b10]);
2912    }
2913
2914    #[test]
2915    fn correction_batch_rejects_wrong_word_count() {
2916        let err =
2917            CorrectionMaskBatch::new(vec![0], vec![Mask { words: vec![0, 0] }], 4).unwrap_err();
2918
2919        assert!(err.to_string().contains("expected 1"));
2920    }
2921
2922    #[test]
2923    fn correction_batch_rejects_duplicate_observable_ids() {
2924        let err = CorrectionMaskBatch::new(
2925            vec![0, 0],
2926            vec![Mask { words: vec![0] }, Mask { words: vec![0] }],
2927            4,
2928        )
2929        .unwrap_err();
2930
2931        assert!(err
2932            .to_string()
2933            .contains("duplicate correction observable id 0"));
2934    }
2935
2936    #[test]
2937    fn correction_batch_validation_rejects_mismatched_public_field_lengths() {
2938        let corrections = CorrectionMaskBatch {
2939            observable_ids: vec![0],
2940            masks: Vec::new(),
2941            shots: 1,
2942        };
2943
2944        let err = corrections.validate_against(&[0], 1).unwrap_err();
2945
2946        assert_eq!(
2947            err.message(),
2948            "observable ids and correction masks must have the same length"
2949        );
2950    }
2951
2952    #[test]
2953    fn correction_batches_require_the_complete_declared_layout() {
2954        for observable_ids in [vec![10], vec![20, 10], vec![10, 20, 30]] {
2955            let masks = vec![Mask::zero(1); observable_ids.len()];
2956            let corrections = CorrectionMaskBatch::new(observable_ids, masks, 1).unwrap();
2957            let err = corrections.validate_against(&[10, 20], 1).unwrap_err();
2958            assert!(err.to_string().contains("observable layout mismatch"));
2959        }
2960    }
2961
2962    #[test]
2963    fn all_checked_decode_paths_require_the_complete_declared_layout() {
2964        struct LayoutOutputWorker {
2965            declared: Vec<i64>,
2966            actual: Vec<i64>,
2967        }
2968
2969        impl NativeDecoderWorker for LayoutOutputWorker {
2970            fn name(&self) -> &str {
2971                "layout-output"
2972            }
2973
2974            fn detector_ids(&self) -> &[i64] {
2975                &[]
2976            }
2977
2978            fn observable_ids(&self) -> &[i64] {
2979                &self.declared
2980            }
2981
2982            fn batch_formats(&self) -> &[DetectorBatchFormat] {
2983                &ALL_BATCH_FORMATS
2984            }
2985
2986            fn decode_batch(
2987                &mut self,
2988                detectors: DetectorBatchView<'_>,
2989            ) -> NpResult<DecoderCorrectionBatch> {
2990                match detectors {
2991                    DetectorBatchView::Masks(view) => {
2992                        Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
2993                            self.actual.clone(),
2994                            vec![Mask::zero(crate::word_count(view.shots)); self.actual.len()],
2995                            view.shots,
2996                        )?))
2997                    }
2998                    DetectorBatchView::Packed(view) => Ok(DecoderCorrectionBatch::Packed(
2999                        PackedObservableShotBatch::zero(self.actual.clone(), view.shots)?,
3000                    )),
3001                    DetectorBatchView::Events(view) => Ok(DecoderCorrectionBatch::Packed(
3002                        PackedObservableShotBatch::zero(self.actual.clone(), view.shots)?,
3003                    )),
3004                }
3005            }
3006        }
3007
3008        for actual in [vec![10, 20], vec![10], vec![20, 10], vec![10, 20, 30]] {
3009            let succeeds = actual == [10, 20];
3010            let mut worker = LayoutOutputWorker {
3011                declared: vec![10, 20],
3012                actual,
3013            };
3014
3015            let mask_view = DetectorMaskBatchView::new(&[], &[], 1).unwrap();
3016            assert_eq!(
3017                worker.decode_batch_checked(mask_view.into()).is_ok(),
3018                succeeds
3019            );
3020
3021            let packed_view = PackedDetectorShotBatchView::new(&[], &[], 1).unwrap();
3022            assert_eq!(
3023                worker.decode_batch_checked(packed_view.into()).is_ok(),
3024                succeeds
3025            );
3026
3027            let offsets = [0, 0];
3028            let event_view = DetectorEventShotBatchView::new(&[], &offsets, &[], 1).unwrap();
3029            assert_eq!(
3030                worker.decode_batch_checked(event_view.into()).is_ok(),
3031                succeeds
3032            );
3033        }
3034    }
3035
3036    #[test]
3037    fn checked_decode_rejects_unknown_observable_id() {
3038        struct UnknownObservableFactory;
3039        struct UnknownObservableWorker;
3040
3041        impl NativeDecoderFactory for UnknownObservableFactory {
3042            fn name(&self) -> &str {
3043                "unknown-observable"
3044            }
3045
3046            fn detector_ids(&self) -> &[i64] {
3047                &[]
3048            }
3049
3050            fn observable_ids(&self) -> &[i64] {
3051                &[0]
3052            }
3053
3054            fn batch_formats(&self) -> &[DetectorBatchFormat] {
3055                &MASKS_BATCH_FORMATS
3056            }
3057
3058            fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
3059                Ok(Box::new(UnknownObservableWorker))
3060            }
3061        }
3062
3063        impl NativeDecoderWorker for UnknownObservableWorker {
3064            fn name(&self) -> &str {
3065                "unknown-observable"
3066            }
3067
3068            fn detector_ids(&self) -> &[i64] {
3069                &[]
3070            }
3071
3072            fn observable_ids(&self) -> &[i64] {
3073                &[0]
3074            }
3075
3076            fn batch_formats(&self) -> &[DetectorBatchFormat] {
3077                &MASKS_BATCH_FORMATS
3078            }
3079
3080            fn decode_batch(
3081                &mut self,
3082                detectors: DetectorBatchView<'_>,
3083            ) -> NpResult<DecoderCorrectionBatch> {
3084                let DetectorBatchView::Masks(detectors) = detectors else {
3085                    return Err(NpError::new("expected Masks"));
3086                };
3087                Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
3088                    vec![1],
3089                    vec![Mask::zero(crate::word_count(detectors.shots))],
3090                    detectors.shots,
3091                )?))
3092            }
3093        }
3094
3095        let factory = UnknownObservableFactory;
3096        let mut decoder = factory.create_worker().unwrap();
3097        let view = DetectorMaskBatchView::new(&[], &[], 4).unwrap();
3098        let err = decoder.decode_batch_checked(view.into()).unwrap_err();
3099
3100        assert!(err
3101            .to_string()
3102            .contains("correction observable layout mismatch: expected [0], got [1]"));
3103    }
3104
3105    #[test]
3106    fn checked_decode_rejects_shots_mismatch() {
3107        struct MismatchedShotsFactory;
3108        struct MismatchedShotsWorker;
3109
3110        impl NativeDecoderFactory for MismatchedShotsFactory {
3111            fn name(&self) -> &str {
3112                "mismatched-shots"
3113            }
3114
3115            fn detector_ids(&self) -> &[i64] {
3116                &[]
3117            }
3118
3119            fn observable_ids(&self) -> &[i64] {
3120                &[0]
3121            }
3122
3123            fn batch_formats(&self) -> &[DetectorBatchFormat] {
3124                &MASKS_BATCH_FORMATS
3125            }
3126
3127            fn create_worker(&self) -> NpResult<Box<dyn NativeDecoderWorker>> {
3128                Ok(Box::new(MismatchedShotsWorker))
3129            }
3130        }
3131
3132        impl NativeDecoderWorker for MismatchedShotsWorker {
3133            fn name(&self) -> &str {
3134                "mismatched-shots"
3135            }
3136
3137            fn detector_ids(&self) -> &[i64] {
3138                &[]
3139            }
3140
3141            fn observable_ids(&self) -> &[i64] {
3142                &[0]
3143            }
3144
3145            fn batch_formats(&self) -> &[DetectorBatchFormat] {
3146                &MASKS_BATCH_FORMATS
3147            }
3148
3149            fn decode_batch(
3150                &mut self,
3151                _detectors: DetectorBatchView<'_>,
3152            ) -> NpResult<DecoderCorrectionBatch> {
3153                Ok(DecoderCorrectionBatch::Masks(CorrectionMaskBatch::new(
3154                    vec![0],
3155                    vec![Mask::zero(crate::word_count(5))],
3156                    5,
3157                )?))
3158            }
3159        }
3160
3161        let factory = MismatchedShotsFactory;
3162        let mut decoder = factory.create_worker().unwrap();
3163        let view = DetectorMaskBatchView::new(&[], &[], 4).unwrap();
3164        let err = decoder.decode_batch_checked(view.into()).unwrap_err();
3165
3166        assert!(err.to_string().contains("expected 4"));
3167    }
3168
3169    #[test]
3170    fn missing_correction_observable_is_zero_residual_correction() {
3171        let corrections = CorrectionMaskBatch::empty(4);
3172        let observables = HashMap::from([(
3173            0,
3174            Mask {
3175                words: vec![0b1010],
3176            },
3177        )]);
3178
3179        let loss =
3180            logical_residual_loss_mask_native(&observables, &corrections, &[0], &Mask::all(4));
3181
3182        assert_eq!(
3183            loss,
3184            Mask {
3185                words: vec![0b1010]
3186            }
3187        );
3188    }
3189
3190    #[test]
3191    fn no_correction_decoder_returns_zero_masks_for_observables() {
3192        let factory = NativeNoCorrectionDecoder::new(vec![0, 2]);
3193        let mut decoder = factory.create_worker().unwrap();
3194        let detector_ids = vec![1];
3195        let detector_masks = vec![Mask {
3196            words: vec![0b1010],
3197        }];
3198        let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
3199
3200        let corrections = decoder
3201            .decode_batch(view.into())
3202            .unwrap()
3203            .into_masks()
3204            .unwrap();
3205
3206        assert_eq!(corrections.observable_ids, vec![0, 2]);
3207        assert_eq!(corrections.masks, vec![Mask { words: vec![0] }; 2]);
3208    }
3209
3210    #[test]
3211    fn no_correction_decoder_returns_zero_packed_rows_for_observables() {
3212        let factory = NativeNoCorrectionDecoder::with_detector_ids(vec![1, 2], vec![0, 3]).unwrap();
3213        let mut decoder = factory.create_worker().unwrap();
3214        let detector_data = vec![0b11, 0b01, 0b10, 0b00];
3215        let detector_ids = decoder.detector_ids().to_vec();
3216        let view = PackedDetectorShotBatchView::new(&detector_ids, &detector_data, 4).unwrap();
3217
3218        let corrections = decoder
3219            .decode_batch_checked(view.into())
3220            .unwrap()
3221            .into_packed()
3222            .unwrap();
3223
3224        assert_eq!(corrections.observable_ids, vec![0, 3]);
3225        assert_eq!(corrections.shots, 4);
3226        assert_eq!(corrections.observable_byte_count, 1);
3227        assert_eq!(corrections.data, vec![0; 4]);
3228    }
3229
3230    #[test]
3231    fn no_correction_decoder_rejects_duplicate_detector_ids() {
3232        let err = NativeNoCorrectionDecoder::with_detector_ids(vec![1, 2, 1], vec![0]).unwrap_err();
3233
3234        assert_eq!(
3235            err.message(),
3236            "decoder detector ids must be unique; duplicate detector id 1"
3237        );
3238    }
3239
3240    #[test]
3241    fn graphlike_detector_copy_constructs_unique_mapping() {
3242        let decoder =
3243            NativeGraphlikeDetectorCopyDecoder::from_graphlike_problem(graphlike_problem())
3244                .unwrap();
3245
3246        assert_eq!(decoder.detector_ids(), &[10, 20]);
3247        assert_eq!(decoder.observable_ids(), &[0, 1]);
3248        assert_eq!(decoder.observable_detector_indices(), &[Some(1), None]);
3249    }
3250
3251    #[test]
3252    fn graphlike_detector_copy_rejects_ambiguous_observable_mapping() {
3253        let mut edges = graphlike_edges();
3254        edges.push(GraphlikeEdge {
3255            detectors: vec![0],
3256            fault_observables: vec![0],
3257            probability: 0.3,
3258            dem_edge_index: 2,
3259        });
3260        let problem = GraphlikeDecodingProblem::new(
3261            vec![10, 20],
3262            vec![Vec::new(), Vec::new()],
3263            vec![0, 1],
3264            edges,
3265        )
3266        .unwrap();
3267
3268        let err = NativeGraphlikeDetectorCopyDecoder::from_graphlike_problem(problem).unwrap_err();
3269
3270        assert!(err
3271            .to_string()
3272            .contains("multiple single-detector candidate edges for observable id 0"));
3273    }
3274
3275    #[test]
3276    fn graphlike_detector_copy_decodes_by_copying_detector_masks() {
3277        let factory =
3278            NativeGraphlikeDetectorCopyDecoder::from_graphlike_problem(graphlike_problem())
3279                .unwrap();
3280        let mut decoder = factory.create_worker().unwrap();
3281        let detector_masks = vec![
3282            Mask {
3283                words: vec![0b0011],
3284            },
3285            Mask {
3286                words: vec![0b1010],
3287            },
3288        ];
3289        let detector_ids = decoder.detector_ids().to_vec();
3290        let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
3291
3292        let corrections = decoder
3293            .decode_batch_checked(view.into())
3294            .unwrap()
3295            .into_masks()
3296            .unwrap();
3297
3298        assert_eq!(corrections.observable_ids, vec![0, 1]);
3299        assert_eq!(
3300            corrections.masks,
3301            vec![
3302                Mask {
3303                    words: vec![0b1010]
3304                },
3305                Mask { words: vec![0] }
3306            ]
3307        );
3308    }
3309
3310    #[test]
3311    fn graphlike_detector_copy_rejects_wrong_detector_order() {
3312        let factory =
3313            NativeGraphlikeDetectorCopyDecoder::from_graphlike_problem(graphlike_problem())
3314                .unwrap();
3315        let mut decoder = factory.create_worker().unwrap();
3316        let detector_ids = vec![20, 10];
3317        let detector_masks = vec![Mask { words: vec![0] }, Mask { words: vec![0] }];
3318        let view = DetectorMaskBatchView::new(&detector_ids, &detector_masks, 4).unwrap();
3319
3320        let err = decoder.decode_batch(view.into()).unwrap_err();
3321
3322        assert!(err.to_string().contains("unexpected order"));
3323    }
3324
3325    #[cfg(feature = "decoder-fusion-blossom")]
3326    #[test]
3327    fn fusion_blossom_scaffold_constructs_from_graphlike_problem() {
3328        let decoder =
3329            NativeFusionBlossomDecoder::from_graphlike_problem(graphlike_problem()).unwrap();
3330
3331        assert_eq!(decoder.name(), "fusion-blossom");
3332        assert_eq!(decoder.detector_ids(), &[10, 20]);
3333        assert_eq!(decoder.observable_ids(), &[0, 1]);
3334        assert_eq!(decoder.edge_count(), 2);
3335    }
3336
3337    #[cfg(feature = "decoder-fusion-blossom")]
3338    #[test]
3339    fn fusion_blossom_scaffold_reports_unavailable_on_decode() {
3340        let factory =
3341            NativeFusionBlossomDecoder::from_graphlike_problem(graphlike_problem()).unwrap();
3342        let mut decoder = factory.create_worker().unwrap();
3343        let detector_data = vec![0; 4];
3344        let detector_ids = decoder.detector_ids().to_vec();
3345        let view = PackedDetectorShotBatchView::new(&detector_ids, &detector_data, 4).unwrap();
3346
3347        let err = decoder.decode_batch_checked(view.into()).unwrap_err();
3348
3349        assert!(err
3350            .to_string()
3351            .contains("no stable Rust dependency is linked yet"));
3352    }
3353}