ramvamp-core 0.1.1

Runtime for streaming fine-grained MoE experts from NVMe: packed format, io_uring reads, LFU expert cache, CPU kernels, KV cache, generation loop
Documentation
//! Typed errors for the file-access layer.

use std::path::PathBuf;

use thiserror::Error;

use crate::format::{FormatError, ProjectionName};

/// Errors from mapping, verifying, or reading installed model files.
///
/// Everything on disk is untrusted until verified, so every failure mode is
/// a typed, recoverable error; this layer never panics on bad input.
#[derive(Debug, Error)]
pub enum IoError {
    /// A format-layer failure: missing manifest entry, size mismatch,
    /// hash mismatch, or an I/O error raised while hashing.
    #[error(transparent)]
    Format(#[from] FormatError),

    /// A filesystem operation failed.
    #[error("{}: {source}", path.display())]
    Io {
        /// Path the operation was acting on.
        path: PathBuf,
        /// Underlying I/O error.
        #[source]
        source: std::io::Error,
    },

    /// A layer index is at or past the layout's layer count.
    #[error("layer {layer} out of range ({n_layers} layers)")]
    LayerOutOfRange {
        /// Requested layer index.
        layer: u32,
        /// Number of layers in the layout.
        n_layers: u32,
    },

    /// An expert index is at or past the layer's expert count.
    #[error("layer {layer}: expert {expert} out of range ({n_experts} experts)")]
    ExpertOutOfRange {
        /// Layer the request was for.
        layer: u32,
        /// Requested expert index.
        expert: u32,
        /// Experts per layer.
        n_experts: u32,
    },

    /// A layer's layout lacks one of the three FFN projections the
    /// streaming FFN needs.
    #[error("layer {layer}: layout has no {name:?} projection")]
    MissingProjection {
        /// Layer whose layout is incomplete.
        layer: u32,
        /// The absent projection.
        name: ProjectionName,
    },

    /// A layout quant name is not a weight format this build can compute.
    #[error("{what}: unknown quant format {quant:?}")]
    UnknownQuant {
        /// Which slab or tensor declared the format.
        what: String,
        /// The unrecognized format name.
        quant: String,
    },

    /// A byte range does not fit the file or buffer it indexes.
    #[error("{what}: range {offset}+{len} out of bounds ({available} bytes)")]
    RangeOutOfBounds {
        /// What was being sliced.
        what: String,
        /// Start of the requested range.
        offset: u64,
        /// Length of the requested range.
        len: u64,
        /// Bytes actually available.
        available: u64,
    },

    /// A 64-bit size in the metadata does not fit this platform's `usize`.
    #[error("{what}: {value} does not fit usize on this platform")]
    TooLarge {
        /// What the value describes.
        what: &'static str,
        /// The oversized value.
        value: u64,
    },

    /// The expert-cache byte budget buys fewer slots per layer than the model
    /// routes experts per step, so no forward pass could ever be served.
    ///
    /// Raised when the stream opens, not when the first step fails: by then
    /// the pool has been allocated and pre-faulted and the model is loaded.
    #[error(
        "expert cache budget of {given} B buys {slots} slot(s) per layer but \
         the model routes {top_k} experts per step; use at least {needed} B \
         ({:.2} MiB)", *needed as f64 / (1024.0 * 1024.0)
    )]
    CacheBudgetTooSmall {
        /// Budget the caller asked for, in bytes.
        given: u64,
        /// Smallest budget that would fit `top_k` slots per layer, in bytes.
        needed: u64,
        /// Slots per layer the budget actually bought.
        slots: u32,
        /// Experts the model routes per step.
        top_k: u32,
    },

    /// Sizing, allocating, or leasing an expert slot buffer failed.
    #[error(transparent)]
    Slots(#[from] crate::io::SlotError),

    /// Planning one routing step against a layer's slots failed.
    #[error(transparent)]
    Cache(#[from] crate::io::CacheError),

    /// A prefill sweep failed.
    ///
    /// Boxed because [`SweepError::Io`](crate::io::SweepError::Io) wraps this
    /// type in the other direction: the two are mutually recursive, so one of
    /// the two edges has to be indirect, and the driver-facing direction is
    /// the one that is taken once per prefill rather than once per read.
    #[error(transparent)]
    Sweep(#[from] Box<crate::io::SweepError>),
}

impl From<crate::io::SweepError> for IoError {
    /// The direction a driver actually writes: `?` on a sweep call inside a
    /// function that reports [`IoError`].
    fn from(error: crate::io::SweepError) -> Self {
        Self::Sweep(Box::new(error))
    }
}

impl IoError {
    /// Attach path context to an I/O error.
    pub(crate) fn io(path: &std::path::Path, source: std::io::Error) -> Self {
        Self::Io {
            path: path.to_path_buf(),
            source,
        }
    }
}