goosedump 0.12.43

// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (C) Jarkko Sakkinen 2026

//! Minimal validated GGUF v3 reader for the fixed inference engines.

use std::borrow::Cow;
use std::collections::HashMap;
use std::fs::File;
use std::path::Path;
use std::str;

use anyhow::{Context as _, Result, anyhow, bail, ensure};
use memmap2::{Mmap, MmapOptions};

const MAGIC: &[u8; 4] = b"GGUF";
const VERSION: u32 = 3;
const DEFAULT_ALIGNMENT: usize = 32;
const MAX_DIMENSIONS: usize = 4;
const Q8_BLOCK_VALUES: usize = 32;
const Q8_BLOCK_BYTES: usize = 34;
const MXFP4_BLOCK_VALUES: usize = 32;
const MXFP4_BLOCK_BYTES: usize = 17;

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(super) enum TensorType {
    F32,
    Bf16,
    Q8_0,
    Mxfp4,
}

impl TensorType {
    /// Encoded byte length of one matrix row for byte-backed formats.
    pub(super) fn encoded_row_bytes(self, width: usize) -> Result<usize> {
        match self {
            Self::F32 => bail!("F32 is not an encoded byte-row format"),
            Self::Bf16 => width
                .checked_mul(size_of::<u16>())
                .ok_or_else(|| anyhow!("BF16 row size overflow")),
            Self::Q8_0 => {
                if !width.is_multiple_of(Q8_BLOCK_VALUES) {
                    bail!("Q8_0 row width is not divisible by 32");
                }
                (width / Q8_BLOCK_VALUES)
                    .checked_mul(Q8_BLOCK_BYTES)
                    .ok_or_else(|| anyhow!("Q8_0 row size overflow"))
            }
            Self::Mxfp4 => {
                if !width.is_multiple_of(MXFP4_BLOCK_VALUES) {
                    bail!("MXFP4 row width is not divisible by 32");
                }
                (width / MXFP4_BLOCK_VALUES)
                    .checked_mul(MXFP4_BLOCK_BYTES)
                    .ok_or_else(|| anyhow!("MXFP4 row size overflow"))
            }
        }
    }
}

/// Validated half-open byte range within the GGUF memory mapping.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(super) struct ByteRange {
    start: usize,
    end: usize,
}

impl ByteRange {
    pub(super) fn new(start: usize, byte_len: usize, limit: usize) -> Result<Self> {
        if byte_len == 0 {
            bail!("byte range must not be empty");
        }
        let end = start
            .checked_add(byte_len)
            .ok_or_else(|| anyhow!("byte range overflow"))?;
        if end > limit {
            bail!("byte range exceeds its containing range");
        }
        Ok(Self { start, end })
    }

    pub(super) const fn start(self) -> usize {
        self.start
    }

    pub(super) const fn end(self) -> usize {
        self.end
    }

    pub(super) const fn len(self) -> usize {
        self.end - self.start
    }

    /// Return one equal contiguous partition of this range.
    pub(super) fn split(self, count: usize, index: usize) -> Result<Self> {
        if count == 0 {
            bail!("byte range partition count must not be zero");
        }
        if index >= count {
            bail!("byte range partition {index} is out of range for {count} partitions");
        }
        let byte_len = self.len();
        if !byte_len.is_multiple_of(count) {
            bail!("byte range of {byte_len} bytes cannot be split into {count} equal partitions");
        }
        let partition_len = byte_len / count;
        let offset = index
            .checked_mul(partition_len)
            .ok_or_else(|| anyhow!("byte range partition offset overflow"))?;
        let start = self
            .start
            .checked_add(offset)
            .ok_or_else(|| anyhow!("byte range partition start overflow"))?;
        Self::new(start, partition_len, self.end)
    }
}

#[derive(Clone, Copy, Debug)]
pub(super) struct Tensor<'a> {
    dimensions: &'a [usize],
    kind: TensorType,
    data: &'a [u8],
}

impl<'a> Tensor<'a> {
    pub(super) fn dimensions(&self) -> &[usize] {
        self.dimensions
    }

    pub(super) fn tensor_type(&self) -> TensorType {
        self.kind
    }

    pub(super) fn f32_slice(&self) -> Result<&'a [f32]> {
        if self.kind != TensorType::F32 {
            bail!("tensor is {:?}, not F32", self.kind);
        }
        if cfg!(target_endian = "big") {
            bail!("F32 tensor views require a little-endian host");
        }
        if !(self.data.as_ptr() as usize).is_multiple_of(align_of::<f32>()) {
            bail!("F32 tensor data is not aligned");
        }
        // Every bit pattern is a valid f32 and the parser checked the byte count.
        // The alignment guard above makes `cast_slice` (which otherwise panics on
        // misalignment) infallible here, with no `unsafe` at the call site.
        Ok(bytemuck::cast_slice(self.data))
    }

    pub(super) fn row_count(&self) -> usize {
        self.dimensions.get(1).copied().unwrap_or(1)
    }

    pub(super) fn f32_row(&self, row: usize) -> Result<&'a [f32]> {
        let width = self.dimensions[0];
        if row >= self.row_count() {
            bail!("F32 row {row} is out of range");
        }
        let values = self.f32_slice()?;
        Ok(&values[row * width..(row + 1) * width])
    }

    /// One encoded matrix row for byte-backed formats (`Bf16`, `Q8_0`, `Mxfp4`).
    pub(super) fn encoded_row(&self, row: usize) -> Result<&'a [u8]> {
        let row_size = self.kind.encoded_row_bytes(self.dimensions[0])?;
        if row >= self.row_count() {
            bail!("{:?} row {row} is out of range", self.kind);
        }
        let start = row
            .checked_mul(row_size)
            .ok_or_else(|| anyhow!("{:?} row offset overflow", self.kind))?;
        Ok(&self.data[start..start + row_size])
    }

    pub(super) fn bf16_row(&self, row: usize) -> Result<&'a [u8]> {
        if self.kind != TensorType::Bf16 {
            bail!("tensor is {:?}, not BF16", self.kind);
        }
        self.encoded_row(row)
    }

    pub(super) fn q8_row(&self, row: usize) -> Result<&'a [u8]> {
        if self.kind != TensorType::Q8_0 {
            bail!("tensor is {:?}, not Q8_0", self.kind);
        }
        self.encoded_row(row)
    }
}

pub(super) struct Gguf {
    file: File,
    bytes: Mmap,
    data_start: usize,
    metadata: HashMap<String, MetadataValue>,
    tensors: HashMap<String, TensorInfo>,
}

impl Gguf {
    pub(super) fn load(path: impl AsRef<Path>) -> Result<Self> {
        let path = path.as_ref();
        let file = File::open(path).with_context(|| format!("open {}", path.display()))?;
        // The mapping is read-only and remains owned by Gguf for every tensor view.
        let bytes = unsafe { MmapOptions::new().map(&file) }
            .with_context(|| format!("map {}", path.display()))?;
        Self::parse(file, bytes).with_context(|| format!("parse {}", path.display()))
    }

    fn parse(file: File, bytes: Mmap) -> Result<Self> {
        let mut reader = Reader::new(&bytes);
        if reader.take(MAGIC.len())? != MAGIC {
            bail!("invalid GGUF magic");
        }
        let version = reader.u32()?;
        if version != VERSION {
            bail!("unsupported GGUF version {version}, expected {VERSION}");
        }
        let tensor_count = reader.count("tensor count")?;
        let metadata_count = reader.count("metadata count")?;
        if metadata_count > reader.remaining() / 13 {
            bail!("metadata count exceeds the file size");
        }

        let mut metadata = HashMap::new();
        for _ in 0..metadata_count {
            let name = reader.string("metadata key")?;
            validate_name(&name, "metadata key")?;
            let value_type = reader.u32()?;
            let value = MetadataValue::read(&mut reader, value_type)
                .with_context(|| format!("read metadata `{name}`"))?;
            if metadata.insert(name.clone(), value).is_some() {
                bail!("duplicate metadata key `{name}`");
            }
        }
        validate_architecture(&metadata)?;
        let alignment = metadata_alignment(&metadata)?;
        if tensor_count > reader.remaining() / 32 {
            bail!("tensor count exceeds the file size");
        }

        let mut tensors = HashMap::new();
        for _ in 0..tensor_count {
            let name = reader.string("tensor name")?;
            validate_name(&name, "tensor name")?;
            let dimension_count =
                usize::try_from(reader.u32()?).context("tensor dimension count")?;
            if !(1..=MAX_DIMENSIONS).contains(&dimension_count) {
                bail!("tensor `{name}` has invalid dimension count {dimension_count}");
            }
            let mut dimensions = Vec::with_capacity(dimension_count);
            for _ in 0..dimension_count {
                let dimension = reader.usize("tensor dimension")?;
                if dimension == 0 {
                    bail!("tensor `{name}` has a zero dimension");
                }
                dimensions.push(dimension);
            }
            let kind = match reader.u32()? {
                0 => TensorType::F32,
                8 => TensorType::Q8_0,
                30 => TensorType::Bf16,
                39 => TensorType::Mxfp4,
                value => bail!("tensor `{name}` uses unsupported GGML type {value}"),
            };
            let offset = reader.usize("tensor offset")?;
            if offset % alignment != 0 {
                bail!("tensor `{name}` offset is not {alignment}-byte aligned");
            }
            let byte_len = tensor_byte_len(&name, &dimensions, kind)?;
            let info = TensorInfo {
                dimensions,
                kind,
                offset,
                byte_len,
            };
            if tensors.insert(name.clone(), info).is_some() {
                bail!("duplicate tensor name `{name}`");
            }
        }
        let data_start = align_up(reader.position(), alignment)?;
        validate_ranges(&bytes, data_start, &tensors)?;
        #[cfg(debug_assertions)]
        validate_q8_weights(&bytes, data_start, &tensors)?;
        Ok(Self {
            file,
            bytes,
            data_start,
            metadata,
            tensors,
        })
    }

    pub(super) fn architecture(&self) -> Result<&str> {
        match self.metadata.get("general.architecture") {
            Some(MetadataValue::String(value)) => Ok(value),
            Some(value) => type_error("general.architecture", "string", value),
            None => bail!("missing GGUF metadata `general.architecture`"),
        }
    }

    pub(super) fn source_file(&self) -> Result<File> {
        self.file.try_clone().context("clone GGUF source file")
    }

    pub(super) fn u32(&self, key: &str) -> Result<u32> {
        match self.value(key)? {
            MetadataValue::U32(value) => Ok(*value),
            value => type_error(key, "u32", value),
        }
    }

    pub(super) fn bool(&self, key: &str) -> Result<bool> {
        match self.value(key)? {
            MetadataValue::Bool(value) => Ok(*value),
            value => type_error(key, "bool", value),
        }
    }

    pub(super) fn f32(&self, key: &str) -> Result<f32> {
        match self.value(key)? {
            MetadataValue::F32(value) => Ok(*value),
            value => type_error(key, "f32", value),
        }
    }

    pub(super) fn string(&self, key: &str) -> Result<&str> {
        match self.value(key)? {
            MetadataValue::String(value) => Ok(value),
            value => type_error(key, "string", value),
        }
    }

    pub(super) fn strings(&self, key: &str) -> Result<&[String]> {
        match self.value(key)? {
            MetadataValue::Array(MetadataArray::String(values)) => Ok(values),
            value => type_error(key, "string array", value),
        }
    }

    pub(super) fn i32s(&self, key: &str) -> Result<Cow<'_, [i32]>> {
        match self.value(key)? {
            MetadataValue::Array(MetadataArray::I32(values)) => Ok(Cow::Borrowed(values)),
            MetadataValue::Array(MetadataArray::U32(values)) => values
                .iter()
                .copied()
                .map(|value| i32::try_from(value).context("token type exceeds i32"))
                .collect::<Result<Vec<_>>>()
                .map(Cow::Owned),
            value => type_error(key, "i32 array", value),
        }
    }

    pub(super) fn tensor(&self, name: &str) -> Result<Tensor<'_>> {
        let info = self
            .tensors
            .get(name)
            .ok_or_else(|| anyhow!("missing tensor `{name}`"))?;
        let range = self.tensor_byte_range(name, info.offset, info.byte_len)?;
        Ok(Tensor {
            dimensions: &info.dimensions,
            kind: info.kind,
            data: &self.bytes[range.start()..range.end()],
        })
    }

    /// Resolve a tensor name to an owned handle for repeated, name-free access.
    pub(super) fn resolve(&self, name: &str) -> Result<TensorHandle> {
        let info = self
            .tensors
            .get(name)
            .ok_or_else(|| anyhow!("missing tensor `{name}`"))?;
        Ok(TensorHandle {
            dimensions: info.dimensions.clone(),
            kind: info.kind,
            byte_range: self.tensor_byte_range(name, info.offset, info.byte_len)?,
        })
    }

    /// Materialize a [`Tensor`] view from a previously resolved handle.
    ///
    /// The handle and `Gguf` must share a common borrow (as when both live on
    /// [`crate::engine::model::gpt_oss::TextModel`]) so dimension and data slices
    /// share one lifetime.
    pub(super) fn tensor_from_handle<'a>(&'a self, handle: &'a TensorHandle) -> Tensor<'a> {
        Tensor {
            dimensions: &handle.dimensions,
            kind: handle.kind,
            data: &self.bytes[handle.byte_range.start()..handle.byte_range.end()],
        }
    }

    fn tensor_byte_range(&self, name: &str, offset: usize, byte_len: usize) -> Result<ByteRange> {
        let start = self
            .data_start
            .checked_add(offset)
            .ok_or_else(|| anyhow!("tensor `{name}` offset overflow"))?;
        ByteRange::new(start, byte_len, self.bytes.len())
            .with_context(|| format!("tensor `{name}` range"))
    }

    fn value(&self, key: &str) -> Result<&MetadataValue> {
        self.metadata
            .get(key)
            .ok_or_else(|| anyhow!("missing GGUF metadata `{key}`"))
    }
}

struct TensorInfo {
    dimensions: Vec<usize>,
    kind: TensorType,
    offset: usize,
    byte_len: usize,
}

/// Owned tensor metadata and validated location resolved once from the name map.
#[derive(Clone, Debug)]
pub(super) struct TensorHandle {
    dimensions: Vec<usize>,
    kind: TensorType,
    byte_range: ByteRange,
}

impl TensorHandle {
    pub(super) const fn byte_range(&self) -> ByteRange {
        self.byte_range
    }

    pub(super) fn partition_from_bytes<'a>(&'a self, data: &'a [u8]) -> Result<Tensor<'a>> {
        let Some((&partition_count, dimensions)) = self.dimensions.split_last() else {
            bail!("tensor has no partition dimension");
        };
        ensure!(
            partition_count != 0,
            "tensor partition count must not be zero"
        );
        ensure!(
            self.byte_range.len().is_multiple_of(partition_count),
            "tensor bytes cannot be split into {partition_count} partitions"
        );
        let expected_len = self.byte_range.len() / partition_count;
        ensure!(
            data.len() == expected_len,
            "tensor partition has {} bytes, expected {expected_len}",
            data.len()
        );
        Ok(Tensor {
            dimensions,
            kind: self.kind,
            data,
        })
    }
}

enum MetadataValue {
    U8,
    I8,
    U16,
    I16,
    U32(u32),
    I32,
    F32(f32),
    Bool(bool),
    String(String),
    Array(MetadataArray),
    U64,
    I64,
    F64,
}

impl MetadataValue {
    fn read(reader: &mut Reader<'_>, kind: u32) -> Result<Self> {
        match kind {
            0 => {
                reader.u8()?;
                Ok(Self::U8)
            }
            1 => {
                reader.i8()?;
                Ok(Self::I8)
            }
            2 => {
                reader.u16()?;
                Ok(Self::U16)
            }
            3 => {
                reader.i16()?;
                Ok(Self::I16)
            }
            4 => Ok(Self::U32(reader.u32()?)),
            5 => {
                reader.i32()?;
                Ok(Self::I32)
            }
            6 => Ok(Self::F32(reader.f32()?)),
            7 => Ok(Self::Bool(reader.bool()?)),
            8 => Ok(Self::String(reader.string("metadata string")?)),
            9 => Ok(Self::Array(MetadataArray::read(reader)?)),
            10 => {
                reader.u64()?;
                Ok(Self::U64)
            }
            11 => {
                reader.i64()?;
                Ok(Self::I64)
            }
            12 => {
                reader.f64()?;
                Ok(Self::F64)
            }
            _ => bail!("unknown GGUF metadata type {kind}"),
        }
    }

    fn type_name(&self) -> &'static str {
        match self {
            Self::U8 => "u8",
            Self::I8 => "i8",
            Self::U16 => "u16",
            Self::I16 => "i16",
            Self::U32(_) => "u32",
            Self::I32 => "i32",
            Self::F32(_) => "f32",
            Self::Bool(_) => "bool",
            Self::String(_) => "string",
            Self::Array(value) => value.type_name(),
            Self::U64 => "u64",
            Self::I64 => "i64",
            Self::F64 => "f64",
        }
    }
}

enum MetadataArray {
    U8,
    I8,
    U16,
    I16,
    U32(Vec<u32>),
    I32(Vec<i32>),
    F32,
    Bool,
    String(Vec<String>),
    U64,
    I64,
    F64,
}

impl MetadataArray {
    fn read(reader: &mut Reader<'_>) -> Result<Self> {
        let kind = reader.u32()?;
        if kind == 9 || kind > 12 {
            bail!("invalid GGUF metadata array type {kind}");
        }
        let count = reader.count("metadata array length")?;
        let minimum = match kind {
            0 | 1 | 7 => 1,
            2 | 3 => 2,
            4..=6 => 4,
            8 | 10..=12 => 8,
            _ => bail!("invalid GGUF metadata array type {kind}"),
        };
        if count > reader.remaining() / minimum {
            bail!("metadata array exceeds the file size");
        }
        Ok(match kind {
            0 => {
                for _ in 0..count {
                    reader.u8()?;
                }
                Self::U8
            }
            1 => {
                for _ in 0..count {
                    reader.i8()?;
                }
                Self::I8
            }
            2 => {
                for _ in 0..count {
                    reader.u16()?;
                }
                Self::U16
            }
            3 => {
                for _ in 0..count {
                    reader.i16()?;
                }
                Self::I16
            }
            4 => Self::U32(
                (0..count)
                    .map(|_| reader.u32())
                    .collect::<Result<Vec<_>>>()?,
            ),
            5 => Self::I32(
                (0..count)
                    .map(|_| reader.i32())
                    .collect::<Result<Vec<_>>>()?,
            ),
            6 => {
                for _ in 0..count {
                    reader.f32()?;
                }
                Self::F32
            }
            7 => {
                for _ in 0..count {
                    reader.bool()?;
                }
                Self::Bool
            }
            8 => Self::String(
                (0..count)
                    .map(|_| reader.string("metadata array string"))
                    .collect::<Result<Vec<_>>>()?,
            ),
            10 => {
                for _ in 0..count {
                    reader.u64()?;
                }
                Self::U64
            }
            11 => {
                for _ in 0..count {
                    reader.i64()?;
                }
                Self::I64
            }
            12 => {
                for _ in 0..count {
                    reader.f64()?;
                }
                Self::F64
            }
            _ => bail!("invalid GGUF metadata array type {kind}"),
        })
    }

    fn type_name(&self) -> &'static str {
        match self {
            Self::U8 => "u8 array",
            Self::I8 => "i8 array",
            Self::U16 => "u16 array",
            Self::I16 => "i16 array",
            Self::U32(_) => "u32 array",
            Self::I32(_) => "i32 array",
            Self::F32 => "f32 array",
            Self::Bool => "bool array",
            Self::String(_) => "string array",
            Self::U64 => "u64 array",
            Self::I64 => "i64 array",
            Self::F64 => "f64 array",
        }
    }
}

struct Reader<'a> {
    bytes: &'a [u8],
    position: usize,
}

impl<'a> Reader<'a> {
    fn new(bytes: &'a [u8]) -> Self {
        Self { bytes, position: 0 }
    }

    fn position(&self) -> usize {
        self.position
    }

    fn remaining(&self) -> usize {
        self.bytes.len() - self.position
    }

    fn take(&mut self, length: usize) -> Result<&'a [u8]> {
        let end = self
            .position
            .checked_add(length)
            .ok_or_else(|| anyhow!("GGUF offset overflow"))?;
        if end > self.bytes.len() {
            bail!("truncated GGUF at byte {}", self.position);
        }
        let value = &self.bytes[self.position..end];
        self.position = end;
        Ok(value)
    }

    fn array<const N: usize>(&mut self) -> Result<[u8; N]> {
        self.take(N)?
            .try_into()
            .map_err(|_| anyhow!("invalid scalar width"))
    }

    fn u8(&mut self) -> Result<u8> {
        Ok(self.take(1)?[0])
    }
    fn i8(&mut self) -> Result<i8> {
        Ok(self.u8()?.cast_signed())
    }
    fn u16(&mut self) -> Result<u16> {
        Ok(u16::from_le_bytes(self.array()?))
    }
    fn i16(&mut self) -> Result<i16> {
        Ok(i16::from_le_bytes(self.array()?))
    }
    fn u32(&mut self) -> Result<u32> {
        Ok(u32::from_le_bytes(self.array()?))
    }
    fn i32(&mut self) -> Result<i32> {
        Ok(i32::from_le_bytes(self.array()?))
    }
    fn f32(&mut self) -> Result<f32> {
        Ok(f32::from_le_bytes(self.array()?))
    }
    fn u64(&mut self) -> Result<u64> {
        Ok(u64::from_le_bytes(self.array()?))
    }
    fn i64(&mut self) -> Result<i64> {
        Ok(i64::from_le_bytes(self.array()?))
    }
    fn f64(&mut self) -> Result<f64> {
        Ok(f64::from_le_bytes(self.array()?))
    }

    fn bool(&mut self) -> Result<bool> {
        match self.u8()? {
            0 => Ok(false),
            1 => Ok(true),
            value => bail!("invalid GGUF boolean {value}"),
        }
    }

    fn usize(&mut self, description: &str) -> Result<usize> {
        let value = self.u64()?;
        usize::try_from(value).map_err(|_| anyhow!("{description} does not fit usize"))
    }

    fn count(&mut self, description: &str) -> Result<usize> {
        self.usize(description)
    }

    fn string(&mut self, description: &str) -> Result<String> {
        let length = self.usize(&format!("{description} length"))?;
        let bytes = self.take(length)?;
        Ok(str::from_utf8(bytes)
            .with_context(|| format!("{description} is not UTF-8"))?
            .to_owned())
    }
}

fn validate_name(name: &str, description: &str) -> Result<()> {
    if name.is_empty() || name.contains('\0') {
        bail!("invalid {description}");
    }
    Ok(())
}

fn validate_architecture(metadata: &HashMap<String, MetadataValue>) -> Result<()> {
    match metadata.get("general.architecture") {
        Some(MetadataValue::String(value)) if !value.is_empty() => Ok(()),
        Some(MetadataValue::String(_)) => bail!("general.architecture is empty"),
        Some(value) => bail!("general.architecture is {}", value.type_name()),
        None => bail!("missing GGUF metadata `general.architecture`"),
    }
}

fn metadata_alignment(metadata: &HashMap<String, MetadataValue>) -> Result<usize> {
    let alignment = match metadata.get("general.alignment") {
        Some(MetadataValue::U32(value)) => usize::try_from(*value)?,
        Some(value) => bail!("general.alignment is {}", value.type_name()),
        None => DEFAULT_ALIGNMENT,
    };
    if !alignment.is_power_of_two() {
        bail!("GGUF alignment must be a nonzero power of two");
    }
    Ok(alignment)
}

fn tensor_byte_len(name: &str, dimensions: &[usize], kind: TensorType) -> Result<usize> {
    let elements = dimensions.iter().try_fold(1_usize, |count, dimension| {
        count
            .checked_mul(*dimension)
            .ok_or_else(|| anyhow!("tensor `{name}` size overflow"))
    })?;
    match kind {
        TensorType::F32 => elements
            .checked_mul(size_of::<f32>())
            .ok_or_else(|| anyhow!("tensor `{name}` byte size overflow")),
        TensorType::Bf16 | TensorType::Q8_0 | TensorType::Mxfp4 => {
            let row_size = kind
                .encoded_row_bytes(dimensions[0])
                .with_context(|| format!("tensor `{name}` row layout"))?;
            let rows = elements / dimensions[0];
            rows.checked_mul(row_size)
                .ok_or_else(|| anyhow!("tensor `{name}` byte size overflow"))
        }
    }
}

fn align_up(value: usize, alignment: usize) -> Result<usize> {
    value
        .checked_add(alignment - 1)
        .map(|value| value & !(alignment - 1))
        .ok_or_else(|| anyhow!("GGUF alignment overflow"))
}

fn validate_ranges(
    bytes: &[u8],
    data_start: usize,
    tensors: &HashMap<String, TensorInfo>,
) -> Result<()> {
    if data_start > bytes.len() {
        bail!("tensor data starts past end of file");
    }
    let mut ranges = Vec::with_capacity(tensors.len());
    for (name, info) in tensors {
        let start = data_start
            .checked_add(info.offset)
            .ok_or_else(|| anyhow!("tensor `{name}` offset overflow"))?;
        let end = start
            .checked_add(info.byte_len)
            .ok_or_else(|| anyhow!("tensor `{name}` range overflow"))?;
        if end > bytes.len() {
            bail!("tensor `{name}` exceeds file size");
        }
        ranges.push((start, end, name));
    }
    ranges.sort_unstable_by_key(|range| range.0);
    for pair in ranges.windows(2) {
        if pair[0].1 > pair[1].0 {
            bail!("tensor `{}` overlaps tensor `{}`", pair[0].2, pair[1].2);
        }
    }
    Ok(())
}

#[cfg(debug_assertions)]
fn validate_q8_weights(
    bytes: &[u8],
    data_start: usize,
    tensors: &HashMap<String, TensorInfo>,
) -> Result<()> {
    for (name, info) in tensors {
        if info.kind != TensorType::Q8_0 {
            continue;
        }
        let start = data_start
            .checked_add(info.offset)
            .context("Q8 tensor offset overflow")?;
        let end = start
            .checked_add(info.byte_len)
            .context("Q8 tensor range overflow")?;
        let data = bytes
            .get(start..end)
            .with_context(|| format!("Q8 tensor `{name}` is out of range"))?;
        for (block, values) in data.chunks_exact(Q8_BLOCK_BYTES).enumerate() {
            let values = values
                .get(size_of::<u16>()..)
                .with_context(|| format!("Q8 tensor `{name}` block {block} is malformed"))?;
            if values.contains(&0x80) {
                bail!("Q8 tensor `{name}` block {block} contains unsupported -128 weight");
            }
        }
    }
    Ok(())
}

fn type_error<T>(key: &str, expected: &str, value: &MetadataValue) -> Result<T> {
    bail!(
        "GGUF metadata `{key}` is {}, expected {expected}",
        value.type_name()
    )
}