ruvix-types

Core kernel interface types for the RuVix Cognition Kernel (ADR-087).

Overview

This crate provides all kernel interface types for RuVix. It is designed to be no_std compatible with zero external dependencies, ensuring it can be used in both kernel code and RVF component code.

The Six Kernel Primitives

RuVix has exactly six kernel primitives:

Primitive	Purpose	Analog
Task	Unit of concurrent execution with capability set	seL4 TCB
Capability	Unforgeable typed token granting access to a resource	seL4 capability
Region	Contiguous memory with access policy	seL4 Untyped + frame
Queue	Typed ring buffer for inter-task communication	io_uring SQ/CQ
Timer	Deadline-driven scheduling primitive	POSIX timer_create
Proof	Cryptographic attestation gating state mutation	Novel (ADR-047)

Type Categories

Handle Types

All kernel objects are referenced through handles:

use ruvix_types::{TaskHandle, CapHandle, RegionHandle, QueueHandle, VectorStoreHandle, GraphHandle};

let task = TaskHandle::new(1, 0);       // Task ID 1, generation 0
let cap = CapHandle::new(42, 1);        // Capability slot 42, epoch 1
let region = RegionHandle::new(0x1000); // Region at ID 0x1000

Capability Rights

Fine-grained access control through bitflags:

use ruvix_types::CapRights;

let read_write = CapRights::READ | CapRights::WRITE;
let full_access = CapRights::all();
let read_only = CapRights::READ;

Available rights: READ, WRITE, GRANT, REVOKE, PROVE, GRANT_ONCE

Proof Types

Cryptographic proof tokens for mutation authorization:

use ruvix_types::{ProofToken, ProofTier, ProofPayload};

// Proof tokens carry tier, nonce, timestamp, and hash
let tier = ProofTier::Reflex;  // <100ns
let tier = ProofTier::Standard; // <100us
let tier = ProofTier::Deep;     // <10ms

Region Policies

Memory access policies:

use ruvix_types::RegionPolicy;

let immutable = RegionPolicy::Immutable;           // Set once, never modified
let append = RegionPolicy::AppendOnly { max_size: 4096 };  // Only append
let slab = RegionPolicy::Slab { slot_size: 64 };   // Fixed-size slots

Constants

Important constants from ADR-087:

use ruvix_types::{ATTESTATION_SIZE, MAX_DELEGATION_DEPTH, REFLEX_CACHE_TTL_MS, REFLEX_CACHE_SIZE};

assert_eq!(ATTESTATION_SIZE, 82);           // ADR-047 witness size
assert_eq!(MAX_DELEGATION_DEPTH, 8);        // Section 20.2
assert_eq!(REFLEX_CACHE_TTL_MS, 100);       // 100ms cache TTL
assert_eq!(REFLEX_CACHE_SIZE, 64);          // 64 entry cache

Features

std (default): Enable standard library support
alloc: Enable alloc crate support for heap allocation

Design Philosophy

Zero dependencies: Pure Rust, no external crates
no_std compatible: Works in kernel and embedded contexts
forbid(unsafe_code): Safety guaranteed at compile time
Exhaustive docs: Every public item is documented

Integration

This crate is the foundation of the RuVix type system. All other ruvix crates depend on it:

ruvix-cap: Capability management using CapHandle, CapRights
ruvix-region: Memory regions using RegionHandle, RegionPolicy
ruvix-queue: IPC queues using QueueHandle, MsgPriority
ruvix-proof: Proof engine using ProofToken, ProofTier
ruvix-vecgraph: Vector stores using VectorKey, CoherenceMeta
ruvix-sched: Scheduler using TaskHandle, TaskPriority

License

MIT OR Apache-2.0

ruvix-types 0.1.0