feat(rvcsi): real nexmon_csi UDP/PCAP fidelity — chanspec decode, libpcap reader, NexmonPcapAdapter

Raises the Nexmon path from a normalized record format to parsing what the
patched Broadcom firmware actually emits, end to end.

napi-c shim (ABI 1.0 -> 1.1, additive):
- rvcsi_nx_csi_udp_header / rvcsi_nx_csi_udp_decode — parse the real nexmon_csi
  UDP payload: the 18-byte header (magic 0x1111, rssi int8, fctl, src_mac[6],
  seq_cnt, core/spatial-stream, Broadcom chanspec, chip_ver) + nsub complex CSI
  samples (modern int16 LE I/Q export — what CSIKit/csireader.py read for the
  BCM43455c0 / 4358 / 4366c0; nsub = (len-18)/4). rvcsi_nx_csi_udp_write to
  synthesize payloads for tests. rvcsi_nx_decode_chanspec — d11ac chanspec ->
  channel (chanspec & 0xff) / bandwidth (bits [13:11], cross-checked against the
  FFT size) / band (bits [15:14], cross-checked against the channel number).
  Still allocation-free, bounds-checked, structured errors, never panics.
- ffi.rs wraps it: decode_chanspec / parse_nexmon_udp_header / decode_nexmon_udp
  / encode_nexmon_udp + DecodedChanspec / NexmonCsiHeader; every unsafe block
  documented; the ABI guard now expects 1.1.

rvcsi-adapter-nexmon:
- pcap.rs — a dependency-free classic-libpcap reader (all four byte-order /
  timestamp-resolution magics; Ethernet / raw-IPv4 / Linux-SLL link types;
  tolerates a truncated final record; pcapng is a follow-up) + extract_udp_payload
  + a synthetic_udp_pcap / synthetic_nexmon_pcap test/example generator.
- NexmonPcapAdapter (a CsiSource) — reads the CSI UDP packets out of a
  `tcpdump -i wlan0 dst port 5500 -w csi.pcap` capture, decodes each via the C
  shim, stamps the frame timestamp from the pcap packet time; non-CSI packets
  counted as "skipped" in health.

rvcsi-runtime: decode_nexmon_pcap, summarize_nexmon_pcap (+ NexmonPcapSummary:
link type, CSI frame count, channels, bandwidths, subcarrier counts, chip
versions, RSSI range, time span), CaptureRuntime::open_nexmon_pcap[_bytes].

rvcsi-node (napi-rs): nexmonDecodePcap, inspectNexmonPcap, decodeChanspec,
RvcsiRuntime.openNexmonPcap. @ruv/rvcsi SDK + .d.ts updated (NexmonPcapSummary,
DecodedChanspec). rvcsi-cli: `record --source nexmon-pcap`, `inspect-nexmon`,
`decode-chanspec`.

161 rvcsi tests pass (adapter-nexmon 9->22), 0 failures, clippy-clean.
ADR-096 §2.2/§2.3/§5, CHANGELOG, CLAUDE.md updated.

https://claude.ai/code/session_01CdYAPvRTjcch6YrYf42n1z

v2/crates/rvcsi-node/Cargo.toml

@@ -18,6 +18,7 @@ crate-type = ["cdylib", "rlib"]
 napi = { workspace = true }
 napi-derive = { workspace = true }
 rvcsi-core = { path = "../rvcsi-core" }
+rvcsi-adapter-nexmon = { path = "../rvcsi-adapter-nexmon" }
 rvcsi-runtime = { path = "../rvcsi-runtime" }
 serde = { workspace = true }
 serde_json = { workspace = true }

v2/crates/rvcsi-node/__test__/api.test.cjs

@@ -18,6 +18,9 @@ test('exports the expected functions and class', () => {
     'rvcsiVersion',
     'nexmonShimAbiVersion',
     'nexmonDecodeRecords',
+    'nexmonDecodePcap',
+    'inspectNexmonPcap',
+    'decodeChanspec',
     'inspectCaptureFile',
     'eventsFromCaptureFile',
     'exportCaptureToRfMemory',
@@ -27,6 +30,7 @@ test('exports the expected functions and class', () => {
   assert.equal(typeof rvcsi.RvCsi, 'function', 'RvCsi should be a class');
   assert.equal(typeof rvcsi.RvCsi.openCaptureFile, 'function');
   assert.equal(typeof rvcsi.RvCsi.openNexmonFile, 'function');
+  assert.equal(typeof rvcsi.RvCsi.openNexmonPcap, 'function');
 });
 
 test('native calls either work (addon built) or fail with a helpful message', () => {

v2/crates/rvcsi-node/index.d.ts

@@ -124,6 +124,35 @@ export interface CaptureSummary {
   calibration_version: string | null;
 }
 
+/** Compact summary of a nexmon_csi `.pcap` capture. */
+export interface NexmonPcapSummary {
+  /** libpcap link-layer type (1 = Ethernet, 101/228 = raw IPv4, 113 = Linux SLL, ...). */
+  link_type: number;
+  csi_frame_count: number;
+  /** Non-CSI / skipped UDP packets (wrong port, not IPv4/UDP, bad nexmon magic). */
+  skipped_packets: number;
+  first_timestamp_ns: number;
+  last_timestamp_ns: number;
+  channels: number[];
+  bandwidths_mhz: number[];
+  subcarrier_counts: number[];
+  /** Distinct chip-version words (e.g. 0x0142 = BCM43455c0). */
+  chip_versions: number[];
+  /** `[min, max]` RSSI in dBm, or `null` for an empty capture. */
+  rssi_dbm_range: [number, number] | null;
+}
+
+/** A decoded Broadcom d11ac chanspec word. */
+export interface DecodedChanspec {
+  /** The raw 16-bit chanspec value. */
+  chanspec: number;
+  /** `chanspec & 0xff`. */
+  channel: number;
+  /** 20 / 40 / 80 / 160, or 0 if the bandwidth bits are unrecognised. */
+  bandwidth_mhz: number;
+  is_5ghz: boolean;
+}
+
 /** rvCSI runtime version string. */
 export function rvcsiVersion(): string;
 
@@ -149,6 +178,23 @@ 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;
 
+/**
+ * Decode the *real* nexmon_csi UDP payloads inside a libpcap `.pcap` buffer
+ * into validated frames. `port` defaults to 5500. Throws on a non-pcap buffer.
+ */
+export function nexmonDecodePcap(
+  pcap: Buffer | Uint8Array,
+  sourceId: string,
+  sessionId: number,
+  port?: number,
+): CsiFrame[];
+
+/** Summarize a nexmon_csi `.pcap` file. `port` defaults to 5500. */
+export function inspectNexmonPcap(path: string, port?: number): NexmonPcapSummary;
+
+/** Decode a Broadcom d11ac chanspec word. */
+export function decodeChanspec(chanspec: number): DecodedChanspec;
+
 /** Streaming capture runtime: a source + the DSP stage + the event pipeline. */
 export class RvCsi {
   private constructor(rt: unknown);
@@ -156,6 +202,8 @@ export class RvCsi {
   static openCaptureFile(path: string): RvCsi;
   /** Open a Nexmon capture file (concatenated rvCSI Nexmon records). */
   static openNexmonFile(path: string, sourceId: string, sessionId: number): RvCsi;
+  /** Open a real nexmon_csi `.pcap` capture. `port` defaults to 5500. */
+  static openNexmonPcap(path: string, sourceId: string, sessionId: number, port?: 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. */

v2/crates/rvcsi-node/index.js

@@ -91,6 +91,41 @@ function exportCaptureToRfMemory(capturePath, outJsonlPath) {
   return binding().exportCaptureToRfMemory(String(capturePath), String(outJsonlPath));
 }
 
+/**
+ * Decode the *real* nexmon_csi UDP payloads inside a libpcap `.pcap` buffer
+ * (`tcpdump -i wlan0 dst port 5500 -w csi.pcap`) into validated CsiFrame objects.
+ * @param {Buffer|Uint8Array} pcap
+ * @param {string} sourceId
+ * @param {number} sessionId
+ * @param {number} [port] CSI UDP port (default 5500)
+ * @returns {import('./index').CsiFrame[]}
+ */
+function nexmonDecodePcap(pcap, sourceId, sessionId, port) {
+  return JSON.parse(
+    binding().nexmonDecodePcap(pcap, String(sourceId), u32(sessionId), port == null ? undefined : Number(port)),
+  );
+}
+
+/**
+ * Summarize a nexmon_csi `.pcap` file (link type, CSI frame count, channels,
+ * bandwidths, chip versions, RSSI range, time span).
+ * @param {string} path
+ * @param {number} [port] CSI UDP port (default 5500)
+ * @returns {import('./index').NexmonPcapSummary}
+ */
+function inspectNexmonPcap(path, port) {
+  return JSON.parse(binding().inspectNexmonPcap(String(path), port == null ? undefined : Number(port)));
+}
+
+/**
+ * Decode a Broadcom d11ac chanspec word.
+ * @param {number} chanspec
+ * @returns {import('./index').DecodedChanspec}
+ */
+function decodeChanspec(chanspec) {
+  return JSON.parse(binding().decodeChanspec(u32(chanspec)));
+}
+
 /** Streaming capture runtime: a source + the DSP stage + the event pipeline. */
 class RvCsi {
   /** @param {*} rt the underlying napi RvcsiRuntime handle */
@@ -112,6 +147,22 @@ class RvCsi {
     return new RvCsi(binding().RvcsiRuntime.openNexmonFile(String(path), String(sourceId), u32(sessionId)));
   }
 
+  /**
+   * Open a real nexmon_csi `.pcap` capture.
+   * @param {string} path @param {string} sourceId @param {number} sessionId
+   * @param {number} [port] CSI UDP port (default 5500) @returns {RvCsi}
+   */
+  static openNexmonPcap(path, sourceId, sessionId, port) {
+    return new RvCsi(
+      binding().RvcsiRuntime.openNexmonPcap(
+        String(path),
+        String(sourceId),
+        u32(sessionId),
+        port == null ? undefined : Number(port),
+      ),
+    );
+  }
+
   /** Next exposable, validated frame, or `null` at end-of-stream. @returns {import('./index').CsiFrame|null} */
   nextFrame() {
     const s = this._rt.nextFrameJson();
@@ -149,6 +200,9 @@ module.exports = {
   rvcsiVersion,
   nexmonShimAbiVersion,
   nexmonDecodeRecords,
+  nexmonDecodePcap,
+  inspectNexmonPcap,
+  decodeChanspec,
   inspectCaptureFile,
   eventsFromCaptureFile,
   exportCaptureToRfMemory,

v2/crates/rvcsi-node/src/lib.rs

@@ -93,6 +93,43 @@ pub fn export_capture_to_rf_memory(capture_path: String, out_jsonl_path: String)
     Ok(n as u32)
 }
 
+/// Decode the *real* nexmon_csi UDP payloads inside a libpcap `.pcap` `Buffer`
+/// into a JSON array of validated `CsiFrame`s. `port` is the CSI UDP port
+/// (omit / `null` ⇒ 5500). Throws if the buffer isn't a parseable classic pcap.
+#[napi]
+pub fn nexmon_decode_pcap(
+    pcap: Buffer,
+    source_id: String,
+    session_id: u32,
+    port: Option<u16>,
+) -> napi::Result<String> {
+    let frames = runtime::decode_nexmon_pcap(pcap.as_ref(), &source_id, session_id as u64, port)
+        .map_err(napi_err)?;
+    to_json(&frames)
+}
+
+/// Summarize a nexmon_csi `.pcap` file (link type, frame counts, channels,
+/// bandwidths, chip versions, RSSI range, time span); returns JSON for a
+/// `NexmonPcapSummary`. `port` defaults to 5500.
+#[napi]
+pub fn inspect_nexmon_pcap(path: String, port: Option<u16>) -> napi::Result<String> {
+    let summary = runtime::summarize_nexmon_pcap(&path, port).map_err(napi_err)?;
+    to_json(&summary)
+}
+
+/// Decode a Broadcom d11ac chanspec word; returns JSON
+/// `{ chanspec, channel, bandwidth_mhz, is_5ghz }`.
+#[napi]
+pub fn decode_chanspec(chanspec: u32) -> napi::Result<String> {
+    let d = rvcsi_adapter_nexmon::decode_chanspec((chanspec & 0xFFFF) as u16);
+    to_json(&serde_json::json!({
+        "chanspec": d.chanspec,
+        "channel": d.channel,
+        "bandwidth_mhz": d.bandwidth_mhz,
+        "is_5ghz": d.is_5ghz,
+    }))
+}
+
 // ---------------------------------------------------------------------------
 // Streaming runtime class
 // ---------------------------------------------------------------------------
@@ -121,6 +158,21 @@ impl RvcsiRuntime {
         })
     }
 
+    /// Open a real nexmon_csi `.pcap` capture as the source. `port` is the CSI
+    /// UDP port (omit / `null` ⇒ 5500).
+    #[napi(factory)]
+    pub fn open_nexmon_pcap(
+        path: String,
+        source_id: String,
+        session_id: u32,
+        port: Option<u16>,
+    ) -> napi::Result<RvcsiRuntime> {
+        Ok(RvcsiRuntime {
+            inner: CaptureRuntime::open_nexmon_pcap(&path, &source_id, session_id as u64, port)
+                .map_err(napi_err)?,
+        })
+    }
+
     /// Next exposable, validated frame as JSON, or `null` at end-of-stream.
     #[napi]
     pub fn next_frame_json(&mut self) -> napi::Result<Option<String>> {