quint 0.0.4

Field algebra for graph canvases — scalar/vector fields over canvas space, node/edge couplings, and evaluation (Rhai authoring, Burn lowering). The portable field source whose forces `seiche` integrates.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
//! Shared resident chunk planes and their zero-copy consumer views.
//!
//! Allocation has one direction here: [`ResidentClient`] allocates each
//! plane through CubeCL, then [`ResidentChunk`] lends Burn and raw wgpu
//! arrangements of that allocation. Neither view imports or copies the
//! plane, and this module deliberately offers no CPU whole-plane read.

use std::{collections::BTreeMap, fmt, mem::size_of_val, num::NonZeroU64};

use burn::tensor::{DType, Shape, Tensor};
use burn_wgpu::{
    CubeTensor, RuntimeOptions, Wgpu, WgpuDevice, WgpuRuntime, WgpuSetup, init_device,
};
use bytemuck::Pod;
use cubecl::{Runtime, client::ComputeClient, server::Handle};

/// Burn's view of one resident `f32` channel plane.
pub type ResidentTensor = Tensor<3>;

/// The host schedule epoch in which a materialized chunk is safe to read.
///
/// This is intentionally a host-issued number, not a frame counter hidden
/// inside quint. The shared device scheduler decides when a submitted write
/// becomes visible to its reader tenants.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ReadEpoch(u64);

impl ReadEpoch {
    pub const fn new(value: u64) -> Self {
        Self(value)
    }

    pub const fn get(self) -> u64 {
        self.0
    }
}

/// Integer world bounds for a resident voxel chunk.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ChunkBounds {
    pub origin: [i64; 3],
    pub extent: [u32; 3],
}

/// A chunk-local dirty box, in cell coordinates.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct DirtyRegion {
    pub origin: [u32; 3],
    pub extent: [u32; 3],
}

/// The fact-bearing class of a channel plane.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PlaneClass {
    /// Canonical values such as occupancy, palette id, provenance, or flags.
    Exact,
    /// Replay-exact numerical state stored as fixed point.
    FixedPoint,
    /// Learned or derived state whose drift does not alter the record.
    Derived,
    /// A work plane, candidate result, mask, or queue.
    Temporary,
}

/// The scalar representation held by one channel plane.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PlaneElementType {
    U8,
    U16,
    U32,
    I8,
    I16,
    I32,
    F32,
}

impl PlaneElementType {
    pub const fn byte_width(self) -> usize {
        match self {
            Self::U8 | Self::I8 => 1,
            Self::U16 | Self::I16 => 2,
            Self::U32 | Self::I32 | Self::F32 => 4,
        }
    }
}

mod sealed {
    pub trait Sealed {}

    impl Sealed for u8 {}
    impl Sealed for u16 {}
    impl Sealed for u32 {}
    impl Sealed for i8 {}
    impl Sealed for i16 {}
    impl Sealed for i32 {}
    impl Sealed for f32 {}
}

/// A scalar that can be uploaded as a resident channel plane.
pub trait ResidentElement: Pod + sealed::Sealed {
    const ELEMENT_TYPE: PlaneElementType;
}

macro_rules! resident_elements {
    ($($ty:ty => $element:ident),+ $(,)?) => {
        $(impl ResidentElement for $ty {
            const ELEMENT_TYPE: PlaneElementType = PlaneElementType::$element;
        })+
    };
}

resident_elements! {
    u8 => U8,
    u16 => U16,
    u32 => U32,
    i8 => I8,
    i16 => I16,
    i32 => I32,
    f32 => F32,
}

/// A named plane in a resident bundle.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct PlaneId(String);

impl PlaneId {
    pub fn new(name: impl Into<String>) -> Result<Self, ResidentChunkError> {
        let name = name.into();
        if name.trim().is_empty() {
            return Err(ResidentChunkError::EmptyPlaneId);
        }
        Ok(Self(name))
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl fmt::Display for PlaneId {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(&self.0)
    }
}

/// Shape and scalar layout of one contiguous 3D plane.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct PlaneLayout {
    pub shape: [usize; 3],
    pub strides: [usize; 3],
    pub element_type: PlaneElementType,
}

impl PlaneLayout {
    fn contiguous<T: ResidentElement>(shape: [usize; 3]) -> Result<Self, ResidentChunkError> {
        if shape.contains(&0) {
            return Err(ResidentChunkError::EmptyShape { shape });
        }
        let yz = shape[1]
            .checked_mul(shape[2])
            .ok_or(ResidentChunkError::ShapeOverflow { shape })?;
        shape[0]
            .checked_mul(yz)
            .and_then(|elements| elements.checked_mul(T::ELEMENT_TYPE.byte_width()))
            .ok_or(ResidentChunkError::ShapeOverflow { shape })?;
        Ok(Self {
            shape,
            strides: [yz, shape[2], 1],
            element_type: T::ELEMENT_TYPE,
        })
    }

    pub fn element_count(self) -> usize {
        self.shape[0] * self.shape[1] * self.shape[2]
    }

    pub fn byte_len(self) -> usize {
        self.element_count() * self.element_type.byte_width()
    }
}

/// Authoritative snapshot metadata copied into every consumer view.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ChunkStamp {
    pub revision: u64,
    pub valid_read_epoch: ReadEpoch,
}

/// Identity of a byte range in one concrete wgpu buffer.
///
/// CubeCL may suballocate several planes from one buffer. Equality therefore
/// checks the wgpu buffer object and the allocation's offset and size, rather
/// than treating any two ranges in the same pooled buffer as one allocation.
#[derive(Clone, Debug)]
pub struct BufferIdentity {
    buffer: wgpu::Buffer,
    offset: u64,
    size: u64,
}

impl BufferIdentity {
    pub fn buffer(&self) -> &wgpu::Buffer {
        &self.buffer
    }

    pub const fn offset(&self) -> u64 {
        self.offset
    }

    pub const fn size(&self) -> u64 {
        self.size
    }

    pub fn same_buffer(&self, other: &Self) -> bool {
        self.buffer == other.buffer
    }
}

impl PartialEq for BufferIdentity {
    fn eq(&self, other: &Self) -> bool {
        self.buffer == other.buffer && self.offset == other.offset && self.size == other.size
    }
}

impl Eq for BufferIdentity {}

/// One raw-kernel arrangement of a resident plane.
///
/// The private CubeCL handle keeps this allocation range leased for as long
/// as the raw view exists, even if its parent chunk is dropped.
#[derive(Debug)]
pub struct RawKernelView {
    allocation: BufferIdentity,
    layout: PlaneLayout,
    class: PlaneClass,
    stamp: ChunkStamp,
    _lease: Handle,
}

impl RawKernelView {
    pub fn allocation(&self) -> &BufferIdentity {
        &self.allocation
    }

    pub const fn layout(&self) -> PlaneLayout {
        self.layout
    }

    pub const fn class(&self) -> PlaneClass {
        self.class
    }

    pub const fn stamp(&self) -> ChunkStamp {
        self.stamp
    }

    /// Everything a consumer outside this crate needs to read the plane,
    /// and nothing it does not.
    ///
    /// Consumers that must not depend on a compute stack (a renderer, a
    /// tracer) spell the lease in their own plain-wgpu terms; this is the
    /// producing side's single definition of what those terms mean, so a
    /// host assembling one cannot invent a field or drop the stamp. The
    /// byte length is derived here rather than restated, which is the
    /// error the consumer-side spellings cannot make on their own.
    pub fn lease(&self) -> SpatialLease<'_> {
        SpatialLease {
            buffer: self.allocation.buffer(),
            offset: self.allocation.offset(),
            size: self.allocation.size(),
            shape: self.layout.shape,
            element_type: self.layout.element_type,
            stamp: self.stamp,
        }
    }

    /// A storage-buffer binding for the exact CubeCL allocation range.
    pub fn binding(&self) -> wgpu::BufferBinding<'_> {
        wgpu::BufferBinding {
            buffer: self.allocation.buffer(),
            offset: self.allocation.offset(),
            size: NonZeroU64::new(self.allocation.size().next_multiple_of(4)),
        }
    }
}

/// The producing side's definition of a resident plane handed outward.
///
/// Deliberately plain: a buffer range, the shape and element type that
/// range holds, and the stamp it was materialized at. A consumer needs
/// exactly this much to copy or bind the plane, and needs no part of
/// CubeCL or Burn to understand it.
///
/// `byte_len` is the load-bearing method. Consumers size their copies
/// from `shape`, and a shape that disagrees with the allocation would
/// walk off the end of the lease into whatever the pool put next to it,
/// which is silent corruption rather than a fault. Checking it is the
/// consumer's obligation and this makes it one line.
#[derive(Clone, Copy, Debug)]
pub struct SpatialLease<'a> {
    pub buffer: &'a wgpu::Buffer,
    pub offset: u64,
    pub size: u64,
    pub shape: [usize; 3],
    pub element_type: PlaneElementType,
    pub stamp: ChunkStamp,
}

impl SpatialLease<'_> {
    /// The bytes `shape` and `element_type` actually describe.
    pub fn byte_len(&self) -> u64 {
        (self.shape[0] * self.shape[1] * self.shape[2] * self.element_type.byte_width()) as u64
    }

    /// Whether the described shape fits the leased range. A consumer that
    /// copies without asking this can read a neighbouring allocation.
    pub fn fits(&self) -> bool {
        self.byte_len() <= self.size
    }
}

/// One Burn arrangement of a resident `f32` plane.
#[derive(Clone, Debug)]
pub struct BurnTensorView {
    tensor: ResidentTensor,
    allocation: BufferIdentity,
    layout: PlaneLayout,
    class: PlaneClass,
    stamp: ChunkStamp,
}

impl BurnTensorView {
    pub fn tensor(&self) -> &ResidentTensor {
        &self.tensor
    }

    pub fn into_tensor(self) -> ResidentTensor {
        self.tensor
    }

    pub fn allocation(&self) -> &BufferIdentity {
        &self.allocation
    }

    pub const fn layout(&self) -> PlaneLayout {
        self.layout
    }

    pub const fn class(&self) -> PlaneClass {
        self.class
    }

    pub const fn stamp(&self) -> ChunkStamp {
        self.stamp
    }
}

/// CubeCL registered on a host-owned wgpu device and queue.
///
/// [`Self::init`] consumes clones in [`WgpuSetup`]; it does not create a
/// second wgpu device. A host that already registered CubeCL can use
/// [`Self::from_registered_device`] instead.
#[derive(Clone)]
pub struct ResidentClient {
    compute: ComputeClient<WgpuRuntime>,
    device: WgpuDevice,
}

impl fmt::Debug for ResidentClient {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("ResidentClient")
            .field("device", &self.device)
            .finish_non_exhaustive()
    }
}

impl ResidentClient {
    pub fn init(setup: WgpuSetup) -> Self {
        let device = init_device(setup, RuntimeOptions::default());
        Self::from_registered_device(device)
    }

    pub fn from_registered_device(device: WgpuDevice) -> Self {
        let compute = WgpuRuntime::client(&device);
        Self { compute, device }
    }

    /// The CubeCL client every resident allocation is made through.
    ///
    /// Public because the field lane allocates its own buffers on the
    /// same client the chunk bundles use: one allocator is what lets a
    /// kernel pass and a tensor pass meet without a bridge.
    pub fn compute_client(&self) -> &ComputeClient<WgpuRuntime> {
        &self.compute
    }

    pub fn device(&self) -> &WgpuDevice {
        &self.device
    }
}

#[derive(Debug)]
struct ResidentPlane {
    handle: Handle,
    layout: PlaneLayout,
    class: PlaneClass,
}

/// A bundle of typed, GPU-resident channel planes for one world chunk.
///
/// `I` is the world's own chunk identity type. quint does not mint a parallel
/// identity model; the wing can carry its existing region key here directly.
#[derive(Debug)]
pub struct ResidentChunk<I> {
    client: ResidentClient,
    identity: I,
    bounds: ChunkBounds,
    stamp: ChunkStamp,
    dirty_regions: Vec<DirtyRegion>,
    planes: BTreeMap<PlaneId, ResidentPlane>,
}

impl<I> ResidentChunk<I> {
    pub fn new(
        client: ResidentClient,
        identity: I,
        bounds: ChunkBounds,
        revision: u64,
        valid_read_epoch: ReadEpoch,
        dirty_regions: Vec<DirtyRegion>,
    ) -> Self {
        Self {
            client,
            identity,
            bounds,
            stamp: ChunkStamp {
                revision,
                valid_read_epoch,
            },
            dirty_regions,
            planes: BTreeMap::new(),
        }
    }

    pub fn identity(&self) -> &I {
        &self.identity
    }

    pub const fn bounds(&self) -> ChunkBounds {
        self.bounds
    }

    pub const fn stamp(&self) -> ChunkStamp {
        self.stamp
    }

    pub fn dirty_regions(&self) -> &[DirtyRegion] {
        &self.dirty_regions
    }

    pub fn plane_ids(&self) -> impl ExactSizeIterator<Item = &PlaneId> {
        self.planes.keys()
    }

    /// Allocate and initialize one contiguous 3D plane through CubeCL.
    pub fn insert_plane<T: ResidentElement>(
        &mut self,
        id: PlaneId,
        class: PlaneClass,
        shape: [usize; 3],
        values: &[T],
    ) -> Result<(), ResidentChunkError> {
        if self.planes.contains_key(&id) {
            return Err(ResidentChunkError::DuplicatePlane(id));
        }
        let layout = PlaneLayout::contiguous::<T>(shape)?;
        let expected = layout.element_count();
        if values.len() != expected {
            return Err(ResidentChunkError::ElementCount {
                plane: id,
                expected,
                actual: values.len(),
            });
        }

        let handle = self
            .compute()
            .create_from_slice(bytemuck::cast_slice(values));
        self.planes.insert(
            id,
            ResidentPlane {
                handle,
                layout,
                class,
            },
        );
        Ok(())
    }

    /// Apply one authority-approved patch without replacing the CubeCL allocation.
    ///
    /// The caller owns the record and the shared-device schedule. Quint checks that
    /// the patch was derived from the resident stamp still being replaced, writes
    /// only the supplied aligned range, then publishes the committed stamp and dirty
    /// regions together. Views minted before this call retain their old stamp and
    /// must be rejected by revision-aware consumers.
    ///
    /// This narrow form accepts a single-plane chunk. A bundle-wide stamp cannot
    /// truthfully advance after one of several planes changes; that case needs one
    /// validated batch commit covering every changed plane.
    pub fn commit_plane_patch<T: ResidentElement>(
        &mut self,
        queue: &wgpu::Queue,
        id: &PlaneId,
        expected_stamp: ChunkStamp,
        element_offset: usize,
        values: &[T],
        committed_stamp: ChunkStamp,
        dirty_regions: Vec<DirtyRegion>,
    ) -> Result<(), ResidentChunkError> {
        if self.stamp != expected_stamp {
            return Err(ResidentChunkError::StaleStamp {
                expected: expected_stamp,
                actual: self.stamp,
            });
        }
        if committed_stamp.revision <= expected_stamp.revision
            || committed_stamp.valid_read_epoch <= expected_stamp.valid_read_epoch
        {
            return Err(ResidentChunkError::NonAdvancingStamp {
                previous: expected_stamp,
                committed: committed_stamp,
            });
        }
        for region in &dirty_regions {
            let fits = !region.extent.contains(&0)
                && (0..3).all(|axis| {
                    region.origin[axis]
                        .checked_add(region.extent[axis])
                        .is_some_and(|end| end <= self.bounds.extent[axis])
                });
            if !fits {
                return Err(ResidentChunkError::DirtyRegionOutOfBounds {
                    region: *region,
                    chunk_extent: self.bounds.extent,
                });
            }
        }

        let plane = self.plane(id)?;
        if self.planes.len() != 1 {
            return Err(ResidentChunkError::PatchRequiresSinglePlane {
                plane_count: self.planes.len(),
            });
        }
        if plane.layout.element_type != T::ELEMENT_TYPE {
            return Err(ResidentChunkError::PatchElementType {
                plane: id.clone(),
                expected: plane.layout.element_type,
                actual: T::ELEMENT_TYPE,
            });
        }

        let byte_offset = element_offset
            .checked_mul(T::ELEMENT_TYPE.byte_width())
            .ok_or_else(|| ResidentChunkError::PatchRangeOverflow { plane: id.clone() })?;
        let byte_len = size_of_val(values);
        let byte_end = byte_offset
            .checked_add(byte_len)
            .ok_or_else(|| ResidentChunkError::PatchRangeOverflow { plane: id.clone() })?;
        if byte_len == 0 || byte_end > plane.layout.byte_len() {
            return Err(ResidentChunkError::PatchRange {
                plane: id.clone(),
                byte_offset,
                byte_len,
                plane_byte_len: plane.layout.byte_len(),
            });
        }

        let alignment = wgpu::COPY_BUFFER_ALIGNMENT as usize;
        if !byte_offset.is_multiple_of(alignment) || !byte_len.is_multiple_of(alignment) {
            return Err(ResidentChunkError::UnalignedPatch {
                plane: id.clone(),
                byte_offset,
                byte_len,
                required_alignment: alignment,
            });
        }

        let allocation = self.allocation(&plane.handle)?;
        queue.write_buffer(
            allocation.buffer(),
            allocation.offset() + byte_offset as u64,
            bytemuck::cast_slice(values),
        );
        self.stamp = committed_stamp;
        self.dirty_regions = dirty_regions;
        Ok(())
    }

    /// Construct a raw storage-buffer view without copying the plane.
    pub fn raw_kernel_view(&self, id: &PlaneId) -> Result<RawKernelView, ResidentChunkError> {
        let plane = self.plane(id)?;
        let allocation = self.allocation(&plane.handle)?;
        Ok(RawKernelView {
            allocation,
            layout: plane.layout,
            class: plane.class,
            stamp: self.stamp,
            _lease: plane.handle.clone(),
        })
    }

    /// Construct a Burn `f32` tensor over the same CubeCL handle.
    ///
    /// This constructor only accepts an `F32` plane. Exact integer planes stay
    /// exact rather than acquiring a lossy float interpretation for convenience.
    pub fn burn_f32_view(&self, id: &PlaneId) -> Result<BurnTensorView, ResidentChunkError> {
        let plane = self.plane(id)?;
        if plane.layout.element_type != PlaneElementType::F32 {
            return Err(ResidentChunkError::BurnElementType {
                plane: id.clone(),
                actual: plane.layout.element_type,
            });
        }
        let allocation = self.allocation(&plane.handle)?;
        let primitive = CubeTensor::<WgpuRuntime>::new_contiguous(
            self.compute().clone(),
            self.client.device.clone(),
            Shape::new(plane.layout.shape),
            plane.handle.clone(),
            DType::F32,
        );
        let tensor = Tensor::from_primitive::<Wgpu>(primitive);
        Ok(BurnTensorView {
            tensor,
            allocation,
            layout: plane.layout,
            class: plane.class,
            stamp: self.stamp,
        })
    }

    fn compute(&self) -> &ComputeClient<WgpuRuntime> {
        &self.client.compute
    }

    fn plane(&self, id: &PlaneId) -> Result<&ResidentPlane, ResidentChunkError> {
        self.planes
            .get(id)
            .ok_or_else(|| ResidentChunkError::UnknownPlane(id.clone()))
    }

    fn allocation(&self, handle: &Handle) -> Result<BufferIdentity, ResidentChunkError> {
        let managed = self
            .compute()
            .get_resource(handle.clone())
            .map_err(|error| ResidentChunkError::Resource(error.to_string()))?;
        let resource = managed.resource();
        Ok(BufferIdentity {
            buffer: resource.buffer.clone(),
            offset: resource.offset,
            size: resource.size,
        })
    }
}

/// Construction and view errors for [`ResidentChunk`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ResidentChunkError {
    EmptyPlaneId,
    EmptyShape {
        shape: [usize; 3],
    },
    ShapeOverflow {
        shape: [usize; 3],
    },
    DuplicatePlane(PlaneId),
    UnknownPlane(PlaneId),
    ElementCount {
        plane: PlaneId,
        expected: usize,
        actual: usize,
    },
    BurnElementType {
        plane: PlaneId,
        actual: PlaneElementType,
    },
    StaleStamp {
        expected: ChunkStamp,
        actual: ChunkStamp,
    },
    NonAdvancingStamp {
        previous: ChunkStamp,
        committed: ChunkStamp,
    },
    DirtyRegionOutOfBounds {
        region: DirtyRegion,
        chunk_extent: [u32; 3],
    },
    PatchRequiresSinglePlane {
        plane_count: usize,
    },
    PatchElementType {
        plane: PlaneId,
        expected: PlaneElementType,
        actual: PlaneElementType,
    },
    PatchRangeOverflow {
        plane: PlaneId,
    },
    PatchRange {
        plane: PlaneId,
        byte_offset: usize,
        byte_len: usize,
        plane_byte_len: usize,
    },
    UnalignedPatch {
        plane: PlaneId,
        byte_offset: usize,
        byte_len: usize,
        required_alignment: usize,
    },
    Resource(String),
}

impl fmt::Display for ResidentChunkError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::EmptyPlaneId => formatter.write_str("resident plane id cannot be empty"),
            Self::EmptyShape { shape } => {
                write!(formatter, "resident plane shape {shape:?} is empty")
            }
            Self::ShapeOverflow { shape } => {
                write!(
                    formatter,
                    "resident plane shape {shape:?} overflows its allocation"
                )
            }
            Self::DuplicatePlane(plane) => {
                write!(formatter, "resident plane {plane} already exists")
            }
            Self::UnknownPlane(plane) => write!(formatter, "resident plane {plane} does not exist"),
            Self::ElementCount {
                plane,
                expected,
                actual,
            } => write!(
                formatter,
                "resident plane {plane} needs {expected} elements, got {actual}"
            ),
            Self::BurnElementType { plane, actual } => write!(
                formatter,
                "resident plane {plane} is {actual:?}, not F32, so it has no Burn float view"
            ),
            Self::StaleStamp { expected, actual } => write!(
                formatter,
                "resident patch expected stamp {expected:?}, but the chunk is at {actual:?}"
            ),
            Self::NonAdvancingStamp {
                previous,
                committed,
            } => write!(
                formatter,
                "resident patch must advance revision and read epoch beyond {previous:?}, got {committed:?}"
            ),
            Self::DirtyRegionOutOfBounds {
                region,
                chunk_extent,
            } => write!(
                formatter,
                "resident dirty region {region:?} does not fit chunk extent {chunk_extent:?}"
            ),
            Self::PatchRequiresSinglePlane { plane_count } => write!(
                formatter,
                "single-plane resident patch cannot restamp a bundle containing {plane_count} planes"
            ),
            Self::PatchElementType {
                plane,
                expected,
                actual,
            } => write!(
                formatter,
                "resident plane {plane} stores {expected:?}, not patch element type {actual:?}"
            ),
            Self::PatchRangeOverflow { plane } => {
                write!(
                    formatter,
                    "resident patch range for plane {plane} overflowed"
                )
            }
            Self::PatchRange {
                plane,
                byte_offset,
                byte_len,
                plane_byte_len,
            } => write!(
                formatter,
                "resident patch [{byte_offset}..{}) does not fit plane {plane}'s {plane_byte_len} bytes",
                byte_offset + byte_len
            ),
            Self::UnalignedPatch {
                plane,
                byte_offset,
                byte_len,
                required_alignment,
            } => write!(
                formatter,
                "resident patch for plane {plane} has byte offset {byte_offset} and length {byte_len}; both must be multiples of {required_alignment}"
            ),
            Self::Resource(error) => write!(formatter, "CubeCL resource export failed: {error}"),
        }
    }
}

impl std::error::Error for ResidentChunkError {}