rvf-types

Core type definitions for the RuVector Format (RVF) binary container.

Overview

rvf-types defines the foundational types shared across all RVF crates:

• Segment headers -- magic bytes, version, flags, checksums
• Enums -- element types (F32, F16, U8, Binary), compression modes, distance metrics
• Flags -- segment-level feature flags (SIMD hints, encryption, quantization tier)

Features

• std -- enable std support (disabled by default for no_std compatibility)
• serde -- derive Serialize/Deserialize on all public types

Usage

[dependencies]
rvf-types = "0.1"

use rvf_types::{SegmentHeader, ElementType, DistanceMetric};

Lineage / Derivation Types

rvf-types defines the types that power DNA-style lineage provenance for RVF files.

DerivationType Enum

Describes how a child file was produced from its parent (#[repr(u8)]):

FileIdentity Struct (68 bytes, repr(C))

Embedded in the Level0Root reserved area at offset 0xF00. Old readers that ignore the reserved area see zeros and continue working.

use rvf_types::FileIdentity;

let root = FileIdentity::new_root([0x42u8; 16]);
assert!(root.is_root());
assert_eq!(root.lineage_depth, 0);

LineageRecord Struct (128 bytes)

A fixed-size record for witness chain entries carrying full derivation metadata:

Lineage Witness Type Constants

These extend the witness chain event types for derivation tracking:

HAS_LINEAGE Segment Flag

Bit 11 (0x0800) of the segment flags bitfield. Set when a file carries DNA-style lineage provenance metadata:

use rvf_types::SegmentFlags;

let flags = SegmentFlags::empty().with(SegmentFlags::HAS_LINEAGE);
assert!(flags.contains(SegmentFlags::HAS_LINEAGE));
assert_eq!(flags.bits(), 0x0800);

Lineage Error Codes (Category 0x06)

Computational Container Types

rvf-types defines the segment types and header structures for the RVF computational container model, which allows .rvf files to carry executable compute alongside vector data.

Segment Types

Two segment type discriminants support the computational container:

These are defined in segment_type.rs and round-trip through TryFrom<u8>:

use rvf_types::SegmentType;

assert_eq!(SegmentType::Kernel as u8, 0x0E);
assert_eq!(SegmentType::Ebpf as u8, 0x0F);
assert_eq!(SegmentType::try_from(0x0E), Ok(SegmentType::Kernel));

KernelHeader (128 bytes, repr(C))

Describes an embedded unikernel or micro-Linux image within a KERNEL_SEG payload. Follows the standard 64-byte SegmentHeader.

EbpfHeader (64 bytes, repr(C))

Describes an embedded eBPF program within an EBPF_SEG payload.

Enums

KernelArch (#[repr(u8)])

KernelType (#[repr(u8)])

ApiTransport (#[repr(u8)])

EbpfProgramType (#[repr(u8)])

EbpfAttachType (#[repr(u8)])

KernelFlags Constants (u32 bitfield)

Three-Tier Execution Model

RVF supports a three-tier execution model where a single .rvf file can carry compute at multiple levels:

Files without KERNEL_SEG or EBPF_SEG continue to work unchanged. Readers that do not recognize these segment types skip them per the RVF forward-compatibility rule. See ADR-030 for the full specification.

License

MIT OR Apache-2.0