rustensor 0.1.0

Small Rust-native checkpoint format for model metadata and tensor weights.
Documentation
use rustensor::{
    CHECKSUM_SIZE, HEADER_SIZE, ModelCheckpoint, ModelMetadata, RustensorError, TensorDType,
    TensorData, WeightLayer, load_checkpoint, save_checkpoint,
};
use std::path::PathBuf;
use std::time::{SystemTime, UNIX_EPOCH};

fn unique_temp_path(name: &str) -> PathBuf {
    let nanos = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_nanos();

    std::env::temp_dir().join(format!(
        "rustensor_{name}_{}_{}.rten",
        std::process::id(),
        nanos
    ))
}

fn sample_checkpoint() -> ModelCheckpoint {
    let metadata = ModelMetadata::new("demo", "mlp", "0.1.0").unwrap();
    let mut checkpoint = ModelCheckpoint::new(metadata);

    checkpoint
        .add_layer(WeightLayer::f32("dense.weight", vec![2], vec![1.0, 2.0]).unwrap())
        .unwrap();

    checkpoint
}

#[test]
fn save_and_load_checkpoint_round_trip() {
    let path = unique_temp_path("roundtrip");
    let checkpoint = sample_checkpoint();

    save_checkpoint(&path, &checkpoint).unwrap();
    let loaded = load_checkpoint(&path).unwrap();

    assert_eq!(loaded, checkpoint);

    let _ = std::fs::remove_file(path);
}

#[test]
fn save_rejects_invalid_checkpoint() {
    let path = unique_temp_path("invalid_checkpoint");
    let metadata = ModelMetadata::new("demo", "mlp", "0.1.0").unwrap();
    let mut checkpoint = ModelCheckpoint::new(metadata);

    checkpoint.layers.push(WeightLayer {
        name: "bad".to_string(),
        shape: vec![2],
        dtype: TensorDType::F32,
        data: TensorData::F32(vec![1.0]),
    });

    let error = save_checkpoint(&path, &checkpoint).unwrap_err();

    assert!(matches!(
        error,
        RustensorError::InvalidTensorDataLength { .. }
    ));

    let _ = std::fs::remove_file(path);
}

#[test]
fn load_rejects_truncated_file() {
    let path = unique_temp_path("truncated_file");

    std::fs::write(&path, b"RTEN").unwrap();

    let error = load_checkpoint(&path).unwrap_err();

    assert!(matches!(error, RustensorError::InvalidHeader));

    let _ = std::fs::remove_file(path);
}

#[test]
fn load_rejects_invalid_magic() {
    let path = unique_temp_path("invalid_magic");
    let checkpoint = sample_checkpoint();

    save_checkpoint(&path, &checkpoint).unwrap();

    let mut bytes = std::fs::read(&path).unwrap();
    bytes[0] = b'X';
    std::fs::write(&path, bytes).unwrap();

    let error = load_checkpoint(&path).unwrap_err();

    assert!(matches!(error, RustensorError::InvalidMagic));

    let _ = std::fs::remove_file(path);
}

#[test]
fn load_rejects_unsupported_version() {
    let path = unique_temp_path("unsupported_version");
    let checkpoint = sample_checkpoint();

    save_checkpoint(&path, &checkpoint).unwrap();

    let mut bytes = std::fs::read(&path).unwrap();
    bytes[4..6].copy_from_slice(&99u16.to_le_bytes());
    std::fs::write(&path, bytes).unwrap();

    let error = load_checkpoint(&path).unwrap_err();

    assert!(matches!(error, RustensorError::UnsupportedVersion { .. }));

    let _ = std::fs::remove_file(path);
}

#[test]
fn load_rejects_invalid_flags() {
    let path = unique_temp_path("invalid_flags");
    let checkpoint = sample_checkpoint();

    save_checkpoint(&path, &checkpoint).unwrap();

    let mut bytes = std::fs::read(&path).unwrap();
    bytes[6..8].copy_from_slice(&1u16.to_le_bytes());
    std::fs::write(&path, bytes).unwrap();

    let error = load_checkpoint(&path).unwrap_err();

    assert!(matches!(error, RustensorError::InvalidFlags { found: 1 }));

    let _ = std::fs::remove_file(path);
}

#[test]
fn load_rejects_mismatched_payload_length() {
    let path = unique_temp_path("bad_payload_length");
    let checkpoint = sample_checkpoint();

    save_checkpoint(&path, &checkpoint).unwrap();

    let mut bytes = std::fs::read(&path).unwrap();
    bytes.pop();
    std::fs::write(&path, bytes).unwrap();

    let error = load_checkpoint(&path).unwrap_err();

    assert!(matches!(error, RustensorError::InvalidPayloadLength { .. }));

    let _ = std::fs::remove_file(path);
}

#[test]
fn load_rejects_tampered_checksum() {
    let path = unique_temp_path("non_zero_checksum");
    let checkpoint = sample_checkpoint();

    save_checkpoint(&path, &checkpoint).unwrap();

    let mut bytes = std::fs::read(&path).unwrap();
    let checksum_start = HEADER_SIZE - CHECKSUM_SIZE;
    bytes[checksum_start] = 1;
    std::fs::write(&path, bytes).unwrap();

    let error = load_checkpoint(&path).unwrap_err();

    assert!(matches!(error, RustensorError::ChecksumMismatch));

    let _ = std::fs::remove_file(path);
}

#[test]
fn load_rejects_invalid_payload_codec() {
    let path = unique_temp_path("invalid_payload_codec");
    let checkpoint = sample_checkpoint();

    save_checkpoint(&path, &checkpoint).unwrap();

    let mut bytes = std::fs::read(&path).unwrap();
    bytes[HEADER_SIZE] ^= 0xFF;
    std::fs::write(&path, bytes).unwrap();

    let error = load_checkpoint(&path).unwrap_err();

    assert!(matches!(
        error,
        RustensorError::ChecksumMismatch
            | RustensorError::DecodeError(_)
            | RustensorError::InvalidMetadata { .. }
            | RustensorError::InvalidTensorDataLength { .. }
    ));

    let _ = std::fs::remove_file(path);
}

#[test]
fn save_writes_rten_header_with_real_checksum() {
    let path = unique_temp_path("real_checksum");
    let checkpoint = sample_checkpoint();

    save_checkpoint(&path, &checkpoint).unwrap();

    let bytes = std::fs::read(&path).unwrap();

    assert!(bytes.len() > HEADER_SIZE);
    assert_eq!(&bytes[0..4], b"RTEN");
    assert_ne!(
        &bytes[HEADER_SIZE - CHECKSUM_SIZE..HEADER_SIZE],
        [0u8; CHECKSUM_SIZE]
    );

    let _ = std::fs::remove_file(path);
}