RVF Model Container Architecture in RuView: Progressive Loading Explained

The RVF (RuView File) format bundles Wi-Fi DensePose model components into a single 64-byte-aligned container with a three-layer progressive loader that delivers instant UI feedback while streaming heavy weights in the background.

The RuView project implements a specialized container format called RVF (RuView File) to package trained Wi-Fi DensePose models for deployment. Understanding the RVF model container architecture is essential for optimizing inference startup times and managing large model artifacts. This article examines how the container structure organizes model weights, metadata, and indices, and details the progressive loading mechanism that enables sub-millisecond initialization.

What is the RVF Model Container?

The RVF format is a single-file container that bundles everything a Wi-Fi DensePose model needs for inference. Unlike standard ONNX or PyTorch checkpoints, RVF segments are self-describing and 64-byte aligned, enabling memory-mapped access and integrity verification via CRC-32.

Container Components and Segment Types

Each RVF file consists of typed segments identified by hexadecimal type codes. According to the source code in rvf_container.rs, the following components are supported:

Component	What it stores	RVF segment type
Manifest (model ID, version, creator)	JSON metadata	0x05
Model weights (raw f32 vector)	Binary f32 array	0x01
Quantisation info	JSON (type, scale, zero point)	0x06
Vital-sign detector config	JSON (breathing/heart-rate bands, window size…)	0x0B
LoRA adaptation profiles	Name + f32 weight array	0x0D
HNSW index for hot-neuron lookup	Binary graph structure	0x02
Overlay graph (pre-computed geometry)	Binary adjacency lists	0x03
SONA environment-specific delta weights	JSON payload	0x36
Witness / training proof	JSON (hash, metrics)	0x0A
Optional WASM inference engine, UI assets, crypto signature	Binary blobs	0x10, 0x11, 0x0C

Segment Header Structure

Every segment begins with a fixed 64-byte header (SegmentHeader) defined in rvf_container.rs. This header contains:

• Magic number and version fields for format validation
• Segment type identifier (e.g., 0x01 for weights)
• Monotonically increasing segment_id
• Payload length in bytes
• CRC-32-based content hash (16 bytes)
• Padding to enforce 64-byte alignment

The alignment requirement ensures that segments can be memory-mapped efficiently and that SIMD operations on weight vectors are cache-line friendly.

Building and Serializing RVF Containers

The RvfBuilder struct in rvf_container.rs provides a fluent API for constructing containers. The build workflow follows three stages:

1. Create a builder – RvfBuilder::new().
2. Push segments – High-level helpers (add_manifest, add_weights, add_quant_info, …) call push_segment. Each call assigns a monotonically increasing segment_id, computes a 16-byte content hash from CRC-32 (crc32_content_hash), and calculates padding to the next 64-byte boundary (align_up).
3. Serialize – build() concatenates [header | payload | padding] for every segment, producing a raw Vec<u8> that can be written to disk via write_to_file.

The corresponding RvfReader validates the magic, version, and content hash during instantiation, exposing helpers such as manifest(), weights(), lora_profile(), and segment_list().

Progressive Loading Mechanism

Large Wi-Fi DensePose models can take seconds to read from disk and deserialize. RuView mitigates this with a three-layer progressive loader implemented in rvf_pipeline.rs.

Three-Layer Architecture

The progressive loader splits model initialization into three distinct latency tiers:

Layer	What is loaded	Typical latency
A (instant)	Manifest, segment directory, optional HNSW index (used only for hot-neuron discovery)	< 5 ms
B (warm)	Subset of weights belonging to "hot" neurons (first-layer nodes of the HNSW graph). If no index exists, the first 25% of the weight vector is used as a fallback.	~ 30% of full load time
C (full)	All remaining weights, overlay graph, SONA profiles, and any optional assets.	Full model readiness

Implementation in rvf_pipeline.rs

The ProgressiveLoader struct is a thin wrapper around RvfReader that orchestrates the three layers:

• ProgressiveLoader::new(data) parses the whole file once to build the segment map.
• load_layer_a() extracts the manifest and calculates n_segments.
• load_layer_b() uses the HNSW index (SEG_INDEX, type 0x02) to find hot neuron IDs, then extracts only those weight entries from the weights segment (0x01).
• load_layer_c() pulls the remaining payloads (full weight vector, overlay graph, LoRA profiles).

Progress is reported via loading_progress() (returning ≈ 0.33, 0.67, 1.0) and the current status can be queried with layer_status().

CLI and API Integration

The sensing server binary in main.rs exposes the progressive loader via the --progressive flag:

# Start the sensing server with progressive loading

target/release/sensing-server --model model.rvf --progressive

When the flag is present, the server initializes the ProgressiveLoader instead of blocking on full deserialization:

if args.progressive || args.model.is_some() {
    info!("Loading trained model (progressive) from {}", mp.display());
    let data = std::fs::read(&mp).expect("model file");
    progressive_loader = Some(ProgressiveLoader::new(&data).expect("loader"));
}

The REST API surfaces layer status through endpoints such as /api/v1/models/info and /api/v1/models/progress, allowing the web UI to display a spinner while Layer A and B are being parsed, then switching to full inference once Layer C completes.

Full-Cycle Code Example

The following example demonstrates building an RVF container, persisting it to disk, and loading it progressively using the RuView APIs:

use rvf_container::{RvfBuilder, VitalSignConfig};

// 1️⃣ Build a model container
let mut builder = RvfBuilder::new();
builder.add_manifest("wifi-densepose-v1", "0.1.0", "Wi-Fi DensePose model");
builder.add_weights(&[0.1_f32, 0.2, 0.3]);               // tiny weight vector
builder.add_quant_info("int8", 0.0078, -128);
builder.add_vital_config(&VitalSignConfig::default());
// optional: HNSW index, overlay graph, LoRA profiles, witness …
let data = builder.build();          // `Vec<u8>` ready to ship

// 2️⃣ Persist to file (optional)
std::fs::write("model.rvf", &data)?;

// 3️⃣ Load with progressive loader
let loader = rvf_pipeline::ProgressiveLoader::new(&data)?;

// Layer A – manifest & quick UI feedback
let a = loader.load_layer_a()?;
// `a.model_name`, `a.version`, `a.n_segments` can be sent to the UI

// Layer B – hot-neuron subset for early inference
let b = loader.load_layer_b()?;
// `b.weights_subset` can be used for a lightweight preview model

// Layer C – full model for accurate inference
let c = loader.load_layer_c()?;
// `c.all_weights`, `c.overlay`, `c.sona_profiles` are now available

Summary

• The RVF model container architecture bundles Wi-Fi DensePose models into a single file with 64-byte aligned segments, each validated by CRC-32 hashes.
• Segment types range from 0x01 (weights) to 0x0B (vital-sign configs), enabling self-describing model artifacts.
• The RvfBuilder and RvfReader in rvf_container.rs handle deterministic serialization and integrity-checked deserialization.
• Progressive loading splits initialization into three layers: Layer A (manifest, <5 ms), Layer B (hot-neuron weights, ~30% load), and Layer C (full weights).
• The ProgressiveLoader in rvf_pipeline.rs orchestrates layer loading, exposing progress via loading_progress() and layer_status().
• CLI integration via --progressive flag and REST API endpoints enable real-time UI feedback during model startup.

Frequently Asked Questions

What is the RVF file format used for in RuView?

The RVF (RuView File) format is a single-file container designed to bundle all components required for Wi-Fi DensePose inference, including model weights, quantization parameters, HNSW indices, and vital-sign detector configurations. It replaces multiple scattered files with a self-describing, 64-byte-aligned binary format that supports integrity verification via CRC-32 hashes and enables memory-mapped access for efficient loading.

How does progressive loading improve model startup time?

Progressive loading reduces time-to-first-inference by splitting model initialization into three layers: Layer A loads the manifest and segment directory in under 5 milliseconds to provide immediate UI feedback; Layer B loads only "hot" neuron weights (approximately 30% of the full model) to enable approximate inference; and Layer C loads remaining weights in the background. This architecture allows the RuView sensing server to begin processing requests before the entire model is resident in memory.

What is the purpose of the 64-byte segment alignment in RVF containers?

The 64-byte alignment requirement for each RVF segment ensures that payload data begins on cache-line boundaries, which optimizes SIMD operations on weight vectors and enables efficient memory mapping on modern operating systems. This alignment is enforced by the align_up function in rvf_container.rs, which calculates padding to the next 64-byte boundary after each segment's payload and content hash.

How are hot neurons identified during Layer B loading?

Hot neurons are identified using the HNSW (Hierarchical Navigable Small World) index stored in segment type 0x02, which maps to the first-layer nodes of the approximate nearest neighbor graph. If the HNSW index is present, load_layer_b() in rvf_pipeline.rs extracts only the weight entries corresponding to these high-traffic neurons; if no index exists, the loader falls back to loading the first 25% of the weight vector as a generic warm-start subset.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}