mirror of
https://github.com/ruvnet/RuView
synced 2026-08-04 19:31:42 +00:00
feat(rvcsi): rvcsi-runtime composition + rvcsi-node (napi-rs) + rvcsi-cli + @ruv/rvcsi TS SDK
- rvcsi-runtime — the composition layer (no FFI): CaptureRuntime (CsiSource + validate_frame + SignalPipeline + EventPipeline, with next_validated_frame / next_clean_frame / drain_events / health) plus one-shot helpers (summarize_capture → CaptureSummary, decode_nexmon_records, events_from_capture, export_capture_to_rf_memory, rf_memory_self_check). 10 tests. - rvcsi-node — the napi-rs seam (cdylib+rlib, build.rs runs napi_build::setup): thin #[napi] wrappers over rvcsi-runtime — rvcsiVersion / nexmonShimAbiVersion / nexmonDecodeRecords / inspectCaptureFile / eventsFromCaptureFile / exportCaptureToRfMemory + an RvcsiRuntime streaming class. Everything that crosses the boundary is a validated/normalized rvCSI struct serialized to JSON (D6). deny(clippy::all). - @ruv/rvcsi npm package (package.json + index.js + index.d.ts + README + __test__/api.test.cjs) — curated JS surface that JSON-parses the addon's output into plain CsiFrame/CsiWindow/CsiEvent/SourceHealth/CaptureSummary objects; lazy native-addon load with a helpful "not built" error. - rvcsi-cli — the `rvcsi` binary: record (Nexmon dump → .rvcsi, validating), inspect, replay, stream, events, health, calibrate (v0 baseline), export ruvector. 7 tests exercising every subcommand against in-memory captures. - rvcsi-cli no longer depends on rvcsi-node (a binary can't link the napi addon); the shared logic moved to rvcsi-runtime. .gitignore: ignore the generated *.node / binding.js / binding.d.ts / npm/ under rvcsi-node. All rvcsi crates: build together OK, clippy-clean, 140 unit/integration tests + 2 doctests, 0 failures (core 29, dsp 28, events 18, adapter-file 20+1, adapter-nexmon 9, ruvector 20+1, runtime 10, cli 7). https://claude.ai/code/session_01CdYAPvRTjcch6YrYf42n1z
This commit is contained in:
Claude
Vendored
+171
@@ -0,0 +1,171 @@
|
||||
// rvCSI Node.js SDK — type declarations for the curated `index.js` surface.
|
||||
//
|
||||
// The shapes below mirror the Rust `rvcsi-core` schema (`CsiFrame`, `CsiWindow`,
|
||||
// `CsiEvent`, `SourceHealth`) and `rvcsi-runtime` (`CaptureSummary`). They are
|
||||
// what you get back after the SDK `JSON.parse`s the strings the napi-rs addon
|
||||
// returns (see ADR-095 §10 / ADR-096 §2.3).
|
||||
|
||||
/** Outcome of the rvCSI validation pipeline for a frame. */
|
||||
export type ValidationStatus =
|
||||
| 'Pending'
|
||||
| 'Accepted'
|
||||
| 'Degraded'
|
||||
| 'Rejected'
|
||||
| 'Recovered';
|
||||
|
||||
/** Which adapter family produced a frame. */
|
||||
export type AdapterKind =
|
||||
| 'File'
|
||||
| 'Replay'
|
||||
| 'Nexmon'
|
||||
| 'Esp32'
|
||||
| 'Intel'
|
||||
| 'Atheros'
|
||||
| 'Synthetic';
|
||||
|
||||
/** Kinds of event the runtime emits. */
|
||||
export type CsiEventKind =
|
||||
| 'PresenceStarted'
|
||||
| 'PresenceEnded'
|
||||
| 'MotionDetected'
|
||||
| 'MotionSettled'
|
||||
| 'BaselineChanged'
|
||||
| 'SignalQualityDropped'
|
||||
| 'DeviceDisconnected'
|
||||
| 'BreathingCandidate'
|
||||
| 'AnomalyDetected'
|
||||
| 'CalibrationRequired';
|
||||
|
||||
/** One normalized, validated CSI observation. */
|
||||
export interface CsiFrame {
|
||||
frame_id: number;
|
||||
session_id: number;
|
||||
source_id: string;
|
||||
adapter_kind: AdapterKind;
|
||||
timestamp_ns: number;
|
||||
channel: number;
|
||||
bandwidth_mhz: number;
|
||||
rssi_dbm: number | null;
|
||||
noise_floor_dbm: number | null;
|
||||
antenna_index: number | null;
|
||||
tx_chain: number | null;
|
||||
rx_chain: number | null;
|
||||
subcarrier_count: number;
|
||||
i_values: number[];
|
||||
q_values: number[];
|
||||
amplitude: number[];
|
||||
phase: number[];
|
||||
validation: ValidationStatus;
|
||||
quality_score: number;
|
||||
/** Present (non-empty) only when `validation` is `Degraded`. */
|
||||
quality_reasons?: string[];
|
||||
calibration_version: string | null;
|
||||
}
|
||||
|
||||
/** A bounded window of frames, summarized. */
|
||||
export interface CsiWindow {
|
||||
window_id: number;
|
||||
session_id: number;
|
||||
source_id: string;
|
||||
start_ns: number;
|
||||
end_ns: number;
|
||||
frame_count: number;
|
||||
mean_amplitude: number[];
|
||||
phase_variance: number[];
|
||||
motion_energy: number;
|
||||
presence_score: number;
|
||||
quality_score: number;
|
||||
}
|
||||
|
||||
/** A detected event with confidence and the windows that justify it. */
|
||||
export interface CsiEvent {
|
||||
event_id: number;
|
||||
kind: CsiEventKind;
|
||||
session_id: number;
|
||||
source_id: string;
|
||||
timestamp_ns: number;
|
||||
confidence: number;
|
||||
evidence_window_ids: number[];
|
||||
calibration_version: string | null;
|
||||
/** Free-form JSON string of event metadata. */
|
||||
metadata_json: string;
|
||||
}
|
||||
|
||||
/** Health snapshot for a source. */
|
||||
export interface SourceHealth {
|
||||
connected: boolean;
|
||||
frames_delivered: number;
|
||||
frames_rejected: number;
|
||||
status: string | null;
|
||||
}
|
||||
|
||||
/** Per-`ValidationStatus` frame counts. */
|
||||
export interface ValidationBreakdown {
|
||||
pending: number;
|
||||
accepted: number;
|
||||
degraded: number;
|
||||
rejected: number;
|
||||
recovered: number;
|
||||
}
|
||||
|
||||
/** Compact summary of a `.rvcsi` capture file. */
|
||||
export interface CaptureSummary {
|
||||
capture_version: number;
|
||||
session_id: number;
|
||||
source_id: string;
|
||||
adapter_kind: string;
|
||||
frame_count: number;
|
||||
first_timestamp_ns: number;
|
||||
last_timestamp_ns: number;
|
||||
channels: number[];
|
||||
subcarrier_counts: number[];
|
||||
mean_quality: number;
|
||||
validation_breakdown: ValidationBreakdown;
|
||||
calibration_version: string | null;
|
||||
}
|
||||
|
||||
/** rvCSI runtime version string. */
|
||||
export function rvcsiVersion(): string;
|
||||
|
||||
/** ABI version of the linked napi-c Nexmon shim (`major<<16 | minor`). */
|
||||
export function nexmonShimAbiVersion(): number;
|
||||
|
||||
/**
|
||||
* Decode a Buffer of "rvCSI Nexmon records" (the napi-c shim format) into
|
||||
* validated frames. Throws on a malformed record.
|
||||
*/
|
||||
export function nexmonDecodeRecords(
|
||||
buf: Buffer | Uint8Array,
|
||||
sourceId: string,
|
||||
sessionId: number,
|
||||
): CsiFrame[];
|
||||
|
||||
/** Summarize a `.rvcsi` capture file. */
|
||||
export function inspectCaptureFile(path: string): CaptureSummary;
|
||||
|
||||
/** Replay a `.rvcsi` capture through the DSP + event pipeline. */
|
||||
export function eventsFromCaptureFile(path: string): CsiEvent[];
|
||||
|
||||
/** Window a capture and store each window's embedding into a JSONL RF-memory file; returns the count. */
|
||||
export function exportCaptureToRfMemory(capturePath: string, outJsonlPath: string): number;
|
||||
|
||||
/** Streaming capture runtime: a source + the DSP stage + the event pipeline. */
|
||||
export class RvCsi {
|
||||
private constructor(rt: unknown);
|
||||
/** Open a `.rvcsi` capture file. */
|
||||
static openCaptureFile(path: string): RvCsi;
|
||||
/** Open a Nexmon capture file (concatenated rvCSI Nexmon records). */
|
||||
static openNexmonFile(path: string, sourceId: string, sessionId: number): RvCsi;
|
||||
/** Next exposable, validated frame, or `null` at end-of-stream. */
|
||||
nextFrame(): CsiFrame | null;
|
||||
/** Like {@link RvCsi.nextFrame} but with the DSP pipeline applied. */
|
||||
nextCleanFrame(): CsiFrame | null;
|
||||
/** Drain the rest of the stream through DSP + the event pipeline. */
|
||||
drainEvents(): CsiEvent[];
|
||||
/** Current health snapshot. */
|
||||
health(): SourceHealth;
|
||||
/** Frames pulled from the source so far. */
|
||||
readonly framesSeen: number;
|
||||
/** Frames dropped by validation so far. */
|
||||
readonly framesDropped: number;
|
||||
}
|
||||
Reference in New Issue
Block a user