Skip to content

README.md

Latest commit

 

History

History
94 lines (70 loc) · 3.46 KB

README.md

File metadata and controls

94 lines (70 loc) · 3.46 KB
Raw

@ruvnet/ruview-kernel

RuView's Rust signal pipeline for JavaScript. The ADR-021 vitals pipeline (wifi-densepose-vitals) is compiled to zero-import WebAssembly (default) and, optionally, a napi-rs native addon. Both expose the same one-function JSON ABI, so results match across backends (ADR-368).

Outputs are signal-processing estimates, not clinical or camera-grade measurements. synthesize() data and every self-test number are SYNTHETIC.

Build from a RuView checkout

rustup target add wasm32-unknown-unknown
cd harness/ruview-kernel
npm run build            # wasm + napi for this platform, with SHA256SUMS
npm test                 # unit, security, and end-to-end tests
node bin/cli.js parity   # wasm vs napi on identical SYNTHETIC input

npm run build:wasm alone is enough for the portable backend.

CLI

ruview-kernel doctor                 # both backends, ABI, integrity
ruview-kernel selftest [--backend wasm|napi|auto]
ruview-kernel synth --seconds 60 --out frames.json
ruview-kernel analyze --file frames.json --readings
ruview-kernel bench --backend napi   # MEASURED on this host only

analyze accepts a JSON array of frames, { "config": {...}, "frames": [...] }, or JSONL (one {"amplitudes":[...],"phases":[...]} per line).

API

import { loadKernel, selfTest } from '@ruvnet/ruview-kernel';

const kernel = loadKernel();                 // wasm; or { backend: 'napi' | 'auto' }
console.log(kernel.backend, kernel.fallbackReason, kernel.integrity);

const { frames } = kernel.synthesize({ seconds: 60, breathing_bpm: 15 });
const report = kernel.analyze(frames, { n_subcarriers: 56, sample_rate_hz: 20 });
console.log(report.summary.last.respiratory);   // { bpm, confidence, status }

const session = kernel.openSession({ n_subcarriers: 56 });
const readings = session.push(frames.slice(0, 200));
session.close();

Binary fast path

analyze() and session.push() automatically send uniform frames as one Float64Array (all amplitudes, then all phases) instead of JSON numbers. Irregular input still goes through JSON, so errors name the bad frame. To skip packing entirely:

const data = new Float64Array(frames * 56 * 2);   // amplitudes…, then phases…
kernel.analyzeFlat(data, { n_subcarriers: 56 }, { phases: true });

MEASURED on one Linux x64 host (ruview-kernel bench --seconds 120): 2.8× (wasm) and 2.5× (napi) faster than the JSON transport for 2 400 frames. The binary path is also bit-exact, while JSON number parsing can move inputs by ULPs.

In a browser, fetch the module yourself and use the filesystem-free entry:

import { loadWasmKernelFromBytes } from '@ruvnet/ruview-kernel/wasm';
const kernel = loadWasmKernelFromBytes(new Uint8Array(await (await fetch(url)).arrayBuffer()));

Backends and trust

Backend Authority Selection
wasm none: module imports nothing, loader rejects any import default
napi full process (native code) backend: 'napi'; never falls back silently
auto napi if present, otherwise wasm with fallbackReason opt-in

Artifacts are checked against SHA256SUMS; a mismatch is always fatal. Requests are bounded (16 MiB, 512 subcarriers, 100 000 frames per call, 64 sessions) and validated before processing.

Metaharness

npx @ruvnet/ruview kernel (MCP tool ruview_kernel_selftest) runs this package's self-test from the RuView harness when it is installed, and reports kernel_not_installed otherwise.