Replace VortexError's variants with a kind, and give every error one

VortexError carried one enum variant per dependency that could fail
(Arrow, FlatBuffers, ObjectStore, Jiff, Tokio, TryFromInt, Prost, Fmt)
plus two structural wrappers (Context, Shared). None were constructed by
name outside the `From` impls or matched on, and the only classification
callers could act on, the `vx_error_code` the C API exports, reported
OTHER for nearly everything: 1966 `vortex_err!` sites and all 1133
`vortex_ensure!` and `vortex_panic!` sites gave no kind at all. It was the
equivalent of a codebase that only ever raises bare `Exception`.

The error type

VortexError is now a struct holding a `VortexErrorKind`, a message, an
optional source and a backtrace, `Arc`-backed so it is cheaply `Clone`.
Errors from dependencies are classified by what they mean to Vortex and
kept as `Error::source`, where callers downcast. `Context` becomes a
message prefix that preserves kind, source and backtrace; `Shared` goes
away. `size_of::<VortexError>()` drops from 88 bytes to 56, and the `?`
conversion path no longer formats eagerly.

The kinds are the C API's existing codes with two additions and one
removal:

- NotFound, for a name lookup that found nothing: a missing field, an
  unknown encoding id, an absent segment. Python raises KeyError here.
- Overflow, for a numeric value that will not fit its target, the largest
  group that was hiding in Other. `From<TryFromIntError>` produces it, so
  `?` on a `try_from` classifies itself.
- Compute is removed. Every other kind names what went wrong; Compute named
  where it happened, which the enum's own docs say a kind must not do. Its
  11 sites were all Overflow, MismatchedTypes or Serde.

NotFound and Overflow take C codes 10 and 11; Compute's slot 2 is retired
and not reused, so no existing code moves. cbindgen regenerated
cinclude/vortex.h and the hand-written C++ mirror in lang/cpp matches.

The macros

`vortex_err!`, `vortex_bail!`, `vortex_ensure!`, `vortex_ensure_eq!` and
`vortex_panic!` now require a leading `Kind:` before any message; the
untagged arm is replaced by a compile error naming the fix, with
compile_fail doctests keeping it that way. The three canned arms
(`MismatchedTypes: expected, actual` and the like) are gone: a literal
is an expr, so `vortex_bail!(MismatchedTypes: "Expected {:?}", x)`
matched the canned arm and rendered its braces verbatim. The 32 sites
that used them spell their message out. The macros no longer inject
`use std::backtrace::Backtrace;` into caller scope.

`vortex_ensure_eq!(a, b)` with no message still reports AssertionFailed,
showing both expressions and values. A check on the caller's input names
its kind alone, `vortex_ensure_eq!(a, b, InvalidArgument)`, and keeps that
output.

The sites

Every construction site now names its kind, each chosen by reading
the site. The rules that settle the ambiguous ones: a check on what the
caller passed in is InvalidArgument or MismatchedTypes, and a length
mismatch is never a type error; a check that a kernel, rewrite or executor
kept its own contract is AssertionFailed; a check made while decoding
metadata or a wire format is Serde; a child index nobody can satisfy is
OutOfBounds however it is phrased. Io covers operating-system and
device-driver calls, so the CUDA, nvcomp and CUB status failures are Io,
as Python's OSError would be. The sites left Other carry it explicitly,
so each reads as a decision.

`From<ArrowError>` sent every Arrow failure to Other; each variant now maps
to its kind (ArithmeticOverflow to Overflow, SchemaError to
MismatchedTypes, the file-format variants to Serde, and so on).
`From<jiff::Error>` maps a date that does not exist or a misused unit to
InvalidArgument. pco's Corruption and InsufficientData map to Serde.

44 sites wrapped an inner VortexError in a fresh `vortex_err!`, which
replaced its kind with a guess and nested its whole Display, backtrace
included, in the new message. A text scan cannot tell those from the same
shape around an io::Error, so a throwaway build probed every `map_err`
closure with a marker type whose must_use warning fires only for a
VortexError. The 29 that wrapped edition-registration calls lose the
`map_err`; the rest use `with_context`, or the `vortex_panic!(err, "...")`
form, which keep the kind. STYLE.md now says to do that.

Python

The Python bindings turned every VortexError into RuntimeError, so none of
this reached Python. Each kind now raises its analogue:

  OutOfBounds      IndexError
  NotFound         KeyError
  Overflow         OverflowError
  InvalidArgument  ValueError
  Serde            ValueError
  MismatchedTypes  TypeError
  NotImplemented   NotImplementedError
  AssertionFailed  AssertionError
  Io               OSError
  Other            RuntimeError

Signed-off-by: Robert Kruszewski <github@robertk.io>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S7EtMqoZ91rrCCh9vS2yTm

Author: robert3005

STYLE.md

@@ -54,8 +54,20 @@
   - `vortex_panic!` for handling invariant violations
   - `vortex_ensure!` and `vortex_ensure_eq!` for checking conditions. Prefer
     `vortex_ensure_eq!(a, b)` with no message: the error already shows both expressions and values.
-    Add a message only for context the expressions lack, and never repeat the values in it.
-- Add context to errors using `.with_context()`
+    Add a message only for context the expressions lack, and never repeat the values in it. With no
+    message the error is `AssertionFailed`; when the check is on the caller's input rather than an
+    internal invariant, name the kind alone, as in `vortex_ensure_eq!(a, b, InvalidArgument)`.
+- Every message names its `VortexErrorKind`, as in `vortex_bail!(InvalidArgument: "...")`; the
+  macros reject a message without one. Choose the kind by what went wrong, the way Python picks an
+  exception class: `InvalidArgument` (`ValueError`) for a value the callee rejects,
+  `MismatchedTypes` (`TypeError`) for the wrong dtype, `OutOfBounds` (`IndexError`) for a position
+  past the end, `NotFound` (`KeyError`) for a name that resolves to nothing, `Overflow`
+  (`OverflowError`) for a value that does not fit its target, `NotImplemented`, `Serde` for an
+  unreadable wire or file format, `Io` for a failed system or driver call, `AssertionFailed` for a
+  broken internal invariant, and `Other` only when nothing else fits. Never classify by where the
+  failure happened.
+- Add context to an existing error with `.with_context()`, which keeps its kind; do not format it
+  into a new `vortex_err!`, which discards the kind.
 - Include backtraces for better debugging
 - Use `VortexExpect` trait when unwrapping is appropriate with proper error context.
 

encodings/alp/src/alp/array.rs

@@ -97,7 +97,7 @@ impl VTable for ALP {
     }
 
     fn buffer(_array: ArrayView<'_, Self>, idx: usize) -> BufferHandle {
-        vortex_panic!("ALPArray buffer index {idx} out of bounds")
+        vortex_panic!(OutOfBounds: "ALPArray buffer index {idx} out of bounds")
     }
 
     fn buffer_name(_array: ArrayView<'_, Self>, _idx: usize) -> Option<String> {
@@ -143,7 +143,7 @@ impl VTable for ALP {
         let encoded_ptype = match &dtype {
             DType::Primitive(PType::F32, n) => DType::Primitive(PType::I32, *n),
             DType::Primitive(PType::F64, n) => DType::Primitive(PType::I64, *n),
-            d => vortex_bail!(MismatchedTypes: "f32 or f64", d),
+            d => vortex_bail!(MismatchedTypes: "expected type: f32 or f64 but instead got {}", d),
         };
         let encoded = children.get(0, &encoded_ptype, len)?;
 
@@ -267,7 +267,7 @@ impl ALPData {
                 encoded.dtype(),
                 DType::Primitive(PType::I32 | PType::I64, _)
             ),
-            "ALP encoded ints have invalid DType {}",
+            MismatchedTypes: "ALP encoded ints have invalid DType {}",
             encoded.dtype(),
         );
 
@@ -276,15 +276,15 @@ impl ALPData {
         let Exponents { e, f } = exponents;
         match encoded.dtype().as_ptype() {
             PType::I32 => {
-                vortex_ensure!(exponents.e <= f32::MAX_EXPONENT, "e out of bounds: {e}");
-                vortex_ensure!(exponents.f <= f32::MAX_EXPONENT, "f out of bounds: {f}");
+                vortex_ensure!(exponents.e <= f32::MAX_EXPONENT, InvalidArgument: "e out of bounds: {e}");
+                vortex_ensure!(exponents.f <= f32::MAX_EXPONENT, InvalidArgument: "f out of bounds: {f}");
                 if let Some(patches) = patches {
                     Self::validate_patches::<f32>(patches, encoded)?;
                 }
             }
             PType::I64 => {
-                vortex_ensure!(e <= f64::MAX_EXPONENT, "e out of bounds: {e}");
-                vortex_ensure!(f <= f64::MAX_EXPONENT, "f out of bounds: {f}");
+                vortex_ensure!(e <= f64::MAX_EXPONENT, InvalidArgument: "e out of bounds: {e}");
+                vortex_ensure!(f <= f64::MAX_EXPONENT, InvalidArgument: "f out of bounds: {f}");
 
                 if let Some(patches) = patches {
                     Self::validate_patches::<f64>(patches, encoded)?;
@@ -295,7 +295,7 @@ impl ALPData {
 
         // Validate patches
         if let Some(patches) = patches {
-            vortex_ensure_eq!(patches.array_len(), encoded.len());
+            vortex_ensure_eq!(patches.array_len(), encoded.len(), InvalidArgument);
 
             // Verify that the patches DType are of the proper DType.
         }
@@ -311,7 +311,9 @@ impl ALPData {
             DType::Primitive(PType::I64, nullability) => {
                 Ok(DType::Primitive(PType::F64, *nullability))
             }
-            _ => vortex_bail!("ALP encoded ints have invalid DType {}", encoded.dtype(),),
+            _ => {
+                vortex_bail!(MismatchedTypes: "ALP encoded ints have invalid DType {}", encoded.dtype(),)
+            }
         }
     }
 
@@ -320,10 +322,10 @@ impl ALPData {
         patches: &Patches,
         encoded: &ArrayRef,
     ) -> VortexResult<()> {
-        vortex_ensure_eq!(patches.array_len(), encoded.len());
+        vortex_ensure_eq!(patches.array_len(), encoded.len(), InvalidArgument);
 
         let expected_type = DType::Primitive(T::PTYPE, encoded.dtype().nullability());
-        vortex_ensure_eq!(patches.dtype(), &expected_type);
+        vortex_ensure_eq!(patches.dtype(), &expected_type, MismatchedTypes);
 
         Ok(())
     }
@@ -437,11 +439,11 @@ fn validate_parts(
 ) -> VortexResult<()> {
     let logical_dtype = ALPData::logical_dtype(encoded)?;
     ALPData::validate_components(encoded, exponents, patches.as_ref())?;
-    vortex_ensure_eq!(encoded.len(), len, "ALP encoded len must match outer len");
+    vortex_ensure_eq!(encoded.len(), len, InvalidArgument: "ALP encoded len must match outer len");
     vortex_ensure_eq!(
         &logical_dtype,
         dtype,
-        "ALP dtype does not match encoded logical dtype"
+        MismatchedTypes: "ALP dtype does not match encoded logical dtype"
     );
     Ok(())
 }

encodings/alp/src/alp/compress.rs

@@ -39,7 +39,7 @@ macro_rules! match_each_alp_float_ptype {
                 type $enc = f64;
                 $body
             }
-            _ => vortex_panic!("ALP can only encode f32 and f64, got {}", ptype),
+            _ => vortex_panic!(MismatchedTypes: "ALP can only encode f32 and f64, got {}", ptype),
         }
     }};
 }
@@ -52,7 +52,7 @@ pub fn alp_encode(
     let (exponents, encoded, patches) = match parray.ptype() {
         PType::F32 => alp_encode_components_typed::<f32>(parray, exponents, ctx)?,
         PType::F64 => alp_encode_components_typed::<f64>(parray, exponents, ctx)?,
-        _ => vortex_bail!("ALP can only encode f32 and f64"),
+        _ => vortex_bail!(MismatchedTypes: "ALP can only encode f32 and f64"),
     };
 
     // SAFETY: alp_encode_components_typed must return well-formed components

encodings/alp/src/alp/compute/compare.rs

@@ -45,7 +45,7 @@ impl CompareKernel for ALP {
         if let Some(const_scalar) = rhs.as_constant() {
             let pscalar = const_scalar.as_primitive_opt().ok_or_else(|| {
                 vortex_err!(
-                    "ALP Compare RHS had the wrong type {}, expected {}",
+                    InvalidArgument: "ALP Compare RHS had the wrong type {}, expected {}",
                     const_scalar,
                     const_scalar.dtype()
                 )
@@ -55,7 +55,7 @@ impl CompareKernel for ALP {
                 match pscalar.typed_value::<T>() {
                     Some(value) => return alp_scalar_compare(lhs, value, operator),
                     None => vortex_bail!(
-                        "Failed to convert scalar {:?} to ALP type {:?}",
+                        InvalidArgument: "Failed to convert scalar {:?} to ALP type {:?}",
                         pscalar,
                         pscalar.ptype()
                     ),

encodings/alp/src/alp/ops.rs

@@ -36,7 +36,7 @@ impl OperationsVTable<ALP> for ALP {
 
         let encoded_val = state
             .slot(ALPSlots::ENCODED)?
-            .ok_or_else(|| vortex_err!("ALP encoded slot is missing"))?
+            .ok_or_else(|| vortex_err!(InvalidArgument: "ALP encoded slot is missing"))?
             .execute_scalar(index, ctx)?;
 
         Ok(match_each_alp_float_ptype!(array.dtype().as_ptype(), |T| {

encodings/alp/src/alp/plugin.rs

@@ -55,7 +55,7 @@ impl ArrayPlugin for ALPPatchedPlugin {
         vortex_ensure_eq!(
             parts.serialized_id,
             self.id(),
-            "ALP plugin does not recognize serialized ID"
+            Serde: "ALP plugin does not recognize serialized ID"
         );
         let alp_array = Array::<ALP>::try_from_parts(ArrayVTable::deserialize(
             &ALP,
@@ -66,7 +66,7 @@ impl ArrayPlugin for ALPPatchedPlugin {
             parts.children,
             session,
         )?)
-        .map_err(|_| vortex_err!("ALP plugin should only deserialize vortex.alp"))?;
+        .map_err(|_| vortex_err!(Serde: "ALP plugin should only deserialize vortex.alp"))?;
 
         // Check if there are interior patches to externalize.
         let Some(patches) = alp_array.patches() else {
@@ -161,15 +161,13 @@ mod tests {
             &SESSION,
         )?;
 
-        let patched: PatchedArray = deserialized
-            .try_downcast()
-            .map_err(|a| vortex_err!("Expected Patched, got {}", a.encoding_id()))?;
+        let patched: PatchedArray = deserialized.try_downcast().map_err(
+            |a| vortex_err!(MismatchedTypes: "Expected Patched, got {}", a.encoding_id()),
+        )?;
 
-        let inner_alp: ALPArray = patched
-            .inner()
-            .clone()
-            .try_downcast()
-            .map_err(|a| vortex_err!("Expected inner ALP, got {}", a.encoding_id()))?;
+        let inner_alp: ALPArray = patched.inner().clone().try_downcast().map_err(
+            |a| vortex_err!(MismatchedTypes: "Expected inner ALP, got {}", a.encoding_id()),
+        )?;
 
         assert!(
             inner_alp.patches().is_none(),
@@ -213,9 +211,9 @@ mod tests {
             &SESSION,
         )?;
 
-        let result = deserialized
-            .try_downcast::<ALP>()
-            .map_err(|a| vortex_err!("Expected deserialized ALP, got {}", a.encoding_id()))?;
+        let result = deserialized.try_downcast::<ALP>().map_err(
+            |a| vortex_err!(Serde: "Expected deserialized ALP, got {}", a.encoding_id()),
+        )?;
 
         assert!(result.patches().is_none(), "Result should not have patches");
 

encodings/alp/src/alp_rd/array.rs

@@ -121,7 +121,7 @@ impl VTable for ALPRD {
     }
 
     fn buffer(_array: ArrayView<'_, Self>, idx: usize) -> BufferHandle {
-        vortex_panic!("ALPRDArray buffer index {idx} out of bounds")
+        vortex_panic!(OutOfBounds: "ALPRDArray buffer index {idx} out of bounds")
     }
 
     fn buffer_name(_array: ArrayView<'_, Self>, _idx: usize) -> Option<String> {
@@ -174,7 +174,7 @@ impl VTable for ALPRD {
         let metadata = ALPRDMetadata::decode(metadata)?;
         if children.len() < 2 {
             vortex_bail!(
-                "Expected at least 2 children for ALPRD encoding, found {}",
+                InvalidArgument: "Expected at least 2 children for ALPRD encoding, found {}",
                 children.len()
             );
         }
@@ -185,8 +185,9 @@ impl VTable for ALPRD {
             [0..metadata.dict_len as usize]
             .iter()
             .map(|&i| {
-                u16::try_from(i)
-                    .map_err(|_| vortex_err!("left_parts_dictionary code {i} does not fit in u16"))
+                u16::try_from(i).map_err(
+                    |_| vortex_err!(Overflow: "left_parts_dictionary code {i} does not fit in u16"),
+                )
             })
             .try_collect()?;
 
@@ -197,7 +198,7 @@ impl VTable for ALPRD {
             DType::Primitive(PType::F64, _) => {
                 DType::Primitive(PType::U64, Nullability::NonNullable)
             }
-            _ => vortex_bail!("Expected f32 or f64 dtype, got {:?}", dtype),
+            _ => vortex_bail!(MismatchedTypes: "Expected f32 or f64 dtype, got {:?}", dtype),
         };
         let right_parts = children.get(1, &right_parts_dtype, len)?;
 
@@ -222,7 +223,7 @@ impl VTable for ALPRD {
             left_parts_dictionary,
             u8::try_from(metadata.right_bit_width).map_err(|_| {
                 vortex_err!(
-                    "right_bit_width {} out of u8 range",
+                    Overflow: "right_bit_width {} out of u8 range",
                     metadata.right_bit_width
                 )
             })?,
@@ -476,18 +477,18 @@ fn validate_parts(
     left_parts_patches: Option<&Patches>,
 ) -> VortexResult<()> {
     if !dtype.is_float() {
-        vortex_bail!("ALPRDArray given invalid DType ({dtype})");
+        vortex_bail!(InvalidArgument: "ALPRDArray given invalid DType ({dtype})");
     }
 
-    vortex_ensure_eq!(left_parts.len(), len);
-    vortex_ensure_eq!(right_parts.len(), len);
+    vortex_ensure_eq!(left_parts.len(), len, InvalidArgument);
+    vortex_ensure_eq!(right_parts.len(), len, InvalidArgument);
 
     if !left_parts.dtype().is_unsigned_int() {
-        vortex_bail!("left_parts dtype must be uint");
+        vortex_bail!(InvalidArgument: "left_parts dtype must be uint");
     }
     if dtype.is_nullable() != left_parts.dtype().is_nullable() {
         vortex_bail!(
-            "ALPRDArray dtype nullability ({}) must match left_parts dtype nullability ({})",
+            InvalidArgument: "ALPRDArray dtype nullability ({}) must match left_parts dtype nullability ({})",
             dtype,
             left_parts.dtype()
         );
@@ -496,12 +497,16 @@ fn validate_parts(
     let expected_right_parts_dtype = match dtype {
         DType::Primitive(PType::F32, _) => DType::Primitive(PType::U32, Nullability::NonNullable),
         DType::Primitive(PType::F64, _) => DType::Primitive(PType::U64, Nullability::NonNullable),
-        _ => vortex_bail!("Expected f32 or f64 dtype, got {:?}", dtype),
+        _ => vortex_bail!(MismatchedTypes: "Expected f32 or f64 dtype, got {:?}", dtype),
     };
-    vortex_ensure_eq!(right_parts.dtype(), &expected_right_parts_dtype);
+    vortex_ensure_eq!(
+        right_parts.dtype(),
+        &expected_right_parts_dtype,
+        MismatchedTypes
+    );
 
     if let Some(patches) = left_parts_patches {
-        vortex_ensure_eq!(patches.array_len(), len);
+        vortex_ensure_eq!(patches.array_len(), len, InvalidArgument);
         // Left-parts exceptions are always all-valid and are stored as the non-nullable left-parts
         // dtype. Requiring that exact dtype (rather than ignoring nullability) means each
         // construction path must produce correct patches, removing the need to normalize them.
@@ -510,7 +515,7 @@ fn validate_parts(
         vortex_ensure_eq!(
             patches.dtype(),
             &expected,
-            "patches dtype must be the non-nullable left_parts dtype"
+            MismatchedTypes: "patches dtype must be the non-nullable left_parts dtype"
         );
     }
 

encodings/alp/src/alp_rd/mod.rs

@@ -146,7 +146,7 @@ where
     T::UINT: NativePType,
 {
     if left_parts.len() != right_parts.len() {
-        vortex_panic!("alp_rd_decode: left_parts.len != right_parts.len");
+        vortex_panic!(AssertionFailed: "alp_rd_decode: left_parts.len != right_parts.len");
     }
 
     if let Some(patches) = left_parts_patches {

encodings/bytebool/src/array.rs

@@ -85,14 +85,14 @@ impl VTable for ByteBool {
     fn buffer(array: ArrayView<'_, Self>, idx: usize) -> BufferHandle {
         match idx {
             0 => array.buffer().clone(),
-            _ => vortex_panic!("ByteBoolArray buffer index {idx} out of bounds"),
+            _ => vortex_panic!(OutOfBounds: "ByteBoolArray buffer index {idx} out of bounds"),
         }
     }
 
     fn buffer_name(_array: ArrayView<'_, Self>, idx: usize) -> Option<String> {
         match idx {
             0 => Some("values".to_string()),
-            _ => vortex_panic!("ByteBoolArray buffer_name index {idx} out of bounds"),
+            _ => vortex_panic!(OutOfBounds: "ByteBoolArray buffer_name index {idx} out of bounds"),
         }
     }
 
@@ -101,7 +101,7 @@ impl VTable for ByteBool {
         array: ArrayView<'_, Self>,
         buffers: &[BufferHandle],
     ) -> VortexResult<ArrayParts<Self>> {
-        vortex_ensure_eq!(buffers.len(), 1);
+        vortex_ensure_eq!(buffers.len(), 1, InvalidArgument);
         let data = ByteBoolData::new(buffers[0].clone());
         Ok(ArrayParts::new(
             self.clone(),
@@ -130,7 +130,7 @@ impl VTable for ByteBool {
     ) -> VortexResult<ArrayParts<Self>> {
         if !metadata.is_empty() {
             vortex_bail!(
-                "ByteBoolArray expects empty metadata, got {} bytes",
+                InvalidArgument: "ByteBoolArray expects empty metadata, got {} bytes",
                 metadata.len()
             );
         }
@@ -140,11 +140,11 @@ impl VTable for ByteBool {
             let validity = children.get(0, &Validity::DTYPE, len)?;
             Validity::Array(validity)
         } else {
-            vortex_bail!("Expected 0 or 1 child, got {}", children.len());
+            vortex_bail!(MismatchedTypes: "Expected 0 or 1 child, got {}", children.len());
         };
 
         if buffers.len() != 1 {
-            vortex_bail!("Expected 1 buffer, got {}", buffers.len());
+            vortex_bail!(InvalidArgument: "Expected 1 buffer, got {}", buffers.len());
         }
         let buffer = buffers[0].clone();
 
@@ -261,10 +261,10 @@ impl ByteBoolData {
         len: usize,
     ) -> VortexResult<()> {
         let expected_dtype = DType::Bool(validity.nullability());
-        vortex_ensure_eq!(dtype, &expected_dtype);
-        vortex_ensure_eq!(buffer.len(), len);
+        vortex_ensure_eq!(dtype, &expected_dtype, MismatchedTypes);
+        vortex_ensure_eq!(buffer.len(), len, InvalidArgument);
         if let Some(vlen) = validity.maybe_len() {
-            vortex_ensure_eq!(vlen, len);
+            vortex_ensure_eq!(vlen, len, InvalidArgument);
         }
         Ok(())
     }