@ruvector/rvf-node 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @ruvector/rvf-node
 
-Node.js native bindings for the RuVector Format (RVF) cognitive container.
+Native Node.js bindings for the [RuVector Format](https://github.com/ruvnet/ruvector/tree/main/crates/rvf) (RVF) vector database. Built with Rust via N-API for native speed with zero serialization overhead.
 
 ## Install
 
@@ -8,52 +8,296 @@ Node.js native bindings for the RuVector Format (RVF) cognitive container.
 npm install @ruvector/rvf-node
 ```
 
-## Usage
+## Features
+
+- **Native Rust performance** via N-API (napi-rs), no FFI marshaling
+- **Single-file vector database** — crash-safe, no WAL, append-only
+- **k-NN search** with HNSW progressive indexing (recall 0.70 → 0.95)
+- **Metadata filtering** — Eq, Ne, Lt, Gt, Range, In, And, Or, Not
+- **Lineage tracking** — DNA-style parent/child derivation chains
+- **Kernel & eBPF embedding** — embed compute alongside vector data
+- **Segment inspection** — enumerate all segments in the file
+- **Cross-platform** — Linux (x86_64, aarch64), macOS (x86_64, Apple Silicon), Windows (x86_64)
+
+## Quick Start
 
 ```javascript
 const { RvfDatabase } = require('@ruvector/rvf-node');
 
-// Create a vector store
-const db = RvfDatabase.create('vectors.rvf', { dimension: 384 });
+// Create a store
+const db = RvfDatabase.create('vectors.rvf', {
+  dimension: 384,
+  metric: 'cosine',
+});
 
 // Insert vectors
-db.ingestBatch(new Float32Array(384), [1]);
+const vectors = new Float32Array(384 * 2); // 2 vectors, 384 dims each
+vectors.fill(0.1);
+db.ingestBatch(vectors, [1, 2]);
 
 // Query nearest neighbors
-const results = db.query(new Float32Array(384), 10);
-console.log(results); // [{ id, distance }]
+const query = new Float32Array(384);
+query.fill(0.15);
+const results = db.query(query, 5);
+// [{ id: 1, distance: 0.002 }, { id: 2, distance: 0.002 }]
+
+db.close();
+```
+
+## API Reference
+
+### Store Lifecycle
+
+```typescript
+// Create a new store
+const db = RvfDatabase.create(path: string, options: RvfOptions);
+
+// Open existing store (read-write, acquires writer lock)
+const db = RvfDatabase.open(path: string);
 
-// Inspect segments
-console.log(db.fileId());       // unique file UUID
-console.log(db.dimension());    // 384
-console.log(db.segments());     // [{ type, id, size }]
+// Open read-only (no lock, concurrent readers allowed)
+const db = RvfDatabase.openReadonly(path: string);
 
+// Close and flush
 db.close();
 ```
 
-## Features
+**RvfOptions:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `dimension` | `number` | required | Vector dimensionality |
+| `metric` | `string` | `"l2"` | `"l2"`, `"cosine"`, or `"inner_product"` |
+| `profile` | `number` | `0` | Hardware profile: 0=Generic, 1=Core, 2=Hot, 3=Full |
+| `signing` | `boolean` | `false` | Enable segment signing |
+| `m` | `number` | `16` | HNSW M parameter (neighbor count) |
+| `efConstruction` | `number` | `200` | HNSW index build quality |
+
+### Ingest Vectors
+
+```typescript
+const result = db.ingestBatch(
+  vectors: Float32Array,  // flat array of n * dimension floats
+  ids: number[],          // vector IDs
+  metadata?: RvfMetadataEntry[]  // optional metadata per vector
+);
+// Returns: { accepted: number, rejected: number, epoch: number }
+```
+
+**Metadata entry format:**
+
+```typescript
+{ fieldId: 0, valueType: 'string', value: 'category_a' }
+{ fieldId: 1, valueType: 'f64',    value: '0.95' }
+{ fieldId: 2, valueType: 'u64',    value: '42' }
+```
+
+### Query
+
+```typescript
+const results = db.query(
+  vector: Float32Array,      // query vector
+  k: number,                 // number of neighbors
+  options?: RvfQueryOptions   // optional search parameters
+);
+// Returns: [{ id: number, distance: number }, ...]
+```
+
+**RvfQueryOptions:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `efSearch` | `number` | `100` | HNSW search quality (higher = better recall, slower) |
+| `filter` | `string` | — | Filter expression as JSON string |
+| `timeoutMs` | `number` | `0` | Query timeout in ms (0 = no timeout) |
+
+### Filter Expressions
+
+Filters are passed as JSON strings. All leaf filters require `fieldId`, `valueType`, and `value`:
+
+```javascript
+// Equality
+db.query(vec, 10, {
+  filter: '{"op":"eq","fieldId":0,"valueType":"string","value":"science"}'
+});
+
+// Range
+db.query(vec, 10, {
+  filter: '{"op":"range","fieldId":1,"valueType":"f64","low":"0.5","high":"1.0"}'
+});
+
+// In-set
+db.query(vec, 10, {
+  filter: '{"op":"in","fieldId":0,"valueType":"u64","values":["1","2","5"]}'
+});
+
+// Boolean combinations
+db.query(vec, 10, {
+  filter: JSON.stringify({
+    op: 'and',
+    children: [
+      { op: 'eq', fieldId: 0, valueType: 'string', value: 'science' },
+      { op: 'gt', fieldId: 1, valueType: 'f64', value: '0.8' }
+    ]
+  })
+});
+
+// Negation
+db.query(vec, 10, {
+  filter: '{"op":"not","child":{"op":"eq","fieldId":0,"valueType":"string","value":"spam"}}'
+});
+```
+
+**Supported operators:** `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `in`, `range`, `and`, `or`, `not`
+
+**Supported value types:** `u64`, `i64`, `f64`, `string`, `bool`
+
+### Delete
+
+```typescript
+// Delete by ID
+const result = db.delete([1, 2, 3]);
+// Returns: { deleted: number, epoch: number }
+
+// Delete by filter
+const result = db.deleteByFilter(
+  '{"op":"gt","fieldId":1,"valueType":"f64","value":"0.9"}'
+);
+```
+
+### Compact
+
+Reclaims space from deleted vectors:
+
+```typescript
+const result = db.compact();
+// Returns: { segmentsCompacted: number, bytesReclaimed: number, epoch: number }
+```
+
+### Status
+
+```typescript
+const status = db.status();
+// {
+//   totalVectors: number,
+//   totalSegments: number,
+//   fileSize: number,
+//   currentEpoch: number,
+//   profileId: number,
+//   compactionState: 'idle' | 'running' | 'emergency',
+//   deadSpaceRatio: number,
+//   readOnly: boolean
+// }
+```
+
+### Lineage & Derivation
+
+RVF tracks parent/child relationships with cryptographic hashes:
+
+```typescript
+db.fileId();        // hex string — unique file identifier
+db.parentId();      // hex string — parent's ID (zeros if root)
+db.lineageDepth();  // 0 for root files
+
+// Derive a child store (inherits dimensions and options)
+const child = db.derive('/tmp/child.rvf');
+child.lineageDepth(); // 1
+child.parentId();     // matches parent's fileId()
+```
+
+### Kernel & eBPF Embedding
+
+Embed compute segments alongside vector data:
+
+```typescript
+// Embed a Linux microkernel
+db.embedKernel(
+  1,                           // arch: 0=x86_64, 1=aarch64
+  0,                           // kernel type
+  0,                           // flags
+  Buffer.from(kernelImage),    // kernel binary
+  8080,                        // API port
+  'console=ttyS0 quiet'       // kernel cmdline (optional)
+);
+
+// Extract kernel
+const kernel = db.extractKernel();
+if (kernel) {
+  console.log(kernel.header);  // Buffer: 128-byte KernelHeader
+  console.log(kernel.image);   // Buffer: kernel image bytes
+}
+
+// Embed an eBPF XDP program
+db.embedEbpf(
+  1,                          // program type (XDP distance)
+  2,                          // attach type (XDP ingress)
+  384,                        // max vector dimension
+  Buffer.from(bytecode),      // BPF ELF object
+  Buffer.from(btf)            // optional BTF section
+);
+
+// Extract eBPF
+const ebpf = db.extractEbpf();
+if (ebpf) {
+  console.log(ebpf.header);   // Buffer: 64-byte EbpfHeader
+  console.log(ebpf.payload);  // Buffer: bytecode + BTF
+}
+```
+
+### Segment Inspection
+
+```typescript
+const segments = db.segments();
+// [{ id: 1, offset: 0, payloadLength: 4096, segType: 'manifest' },
+//  { id: 2, offset: 4160, payloadLength: 51200, segType: 'vec' },
+//  { id: 3, offset: 55424, payloadLength: 12288, segType: 'index' }]
+
+db.dimension(); // 384
+```
+
+## Self-Booting RVF
+
+An `.rvf` file can embed a Linux kernel, eBPF programs, and SSH keys alongside vector data — producing a single file that boots as a microservice.
+
+The Claude Code Appliance example builds a complete AI dev environment:
+
+```bash
+cd examples/rvf
+cargo run --example claude_code_appliance
+```
+
+```
+claude_code_appliance.rvf
+  ├── KERNEL_SEG    Linux 6.8.12 bzImage (5.2 MB, x86_64)
+  ├── EBPF_SEG      Socket filter — ports 2222, 8080 only
+  ├── VEC_SEG       20 package embeddings (128-dim)
+  ├── INDEX_SEG     HNSW graph for package search
+  ├── WITNESS_SEG   6-entry tamper-evident audit trail
+  └── CRYPTO_SEG    3 Ed25519 SSH user keys
+```
+
+Final file: **5.1 MB single `.rvf`** — boots Linux, serves queries, runs Claude Code.
+
+See the [full RVF documentation](https://github.com/ruvnet/ruvector/tree/main/crates/rvf) for details.
+
+## Build from Source
+
+```bash
+# Prerequisites: Rust 1.87+, Node.js 18+
+cd crates/rvf/rvf-node
+npm install
+npm run build
+```
+
+## Related Packages
 
-- Native performance via N-API bindings to Rust `rvf-runtime`
-- Full store lifecycle: create, open, ingest, query, delete, compact
-- Lineage tracking with FileIdentity derivation chains
-- Kernel/eBPF segment inspection
-- Cross-platform: Linux x64/arm64, macOS x64/arm64, Windows x64
-
-## API
-
-| Method | Description |
-|--------|-------------|
-| `RvfDatabase.create(path, options)` | Create a new RVF store |
-| `RvfDatabase.open(path)` | Open an existing store |
-| `db.ingestBatch(vectors, ids)` | Insert vectors |
-| `db.query(vector, k)` | k-NN similarity search |
-| `db.delete(ids)` | Delete vectors by ID |
-| `db.compact()` | Reclaim deleted space |
-| `db.status()` | Get store stats |
-| `db.segments()` | List all segments |
-| `db.fileId()` | Get unique file UUID |
-| `db.close()` | Close and release lock |
+| Package | Description |
+|---------|-------------|
+| [`@ruvector/rvf`](https://www.npmjs.com/package/@ruvector/rvf) | Unified TypeScript SDK |
+| [`@ruvector/rvf-wasm`](https://www.npmjs.com/package/@ruvector/rvf-wasm) | Browser WASM package |
+| [`@ruvector/rvf-mcp-server`](https://www.npmjs.com/package/@ruvector/rvf-mcp-server) | MCP server for AI agents |
+| [`rvf-runtime`](https://crates.io/crates/rvf-runtime) | Rust runtime (powers this package) |
 
 ## License
 
-MIT
+MIT OR Apache-2.0

package/index.d.ts

@@ -0,0 +1,95 @@
+/* auto-generated: TypeScript declarations for @ruvector/rvf-node */
+
+export interface RvfOptions {
+  dimension: number;
+  metric?: string;
+  profile?: number;
+  signing?: boolean;
+  m?: number;
+  efConstruction?: number;
+}
+
+export interface RvfQueryOptions {
+  efSearch?: number;
+  filter?: string;
+  timeoutMs?: number;
+}
+
+export interface RvfSearchResult {
+  id: number;
+  distance: number;
+}
+
+export interface RvfIngestResult {
+  accepted: number;
+  rejected: number;
+  epoch: number;
+}
+
+export interface RvfDeleteResult {
+  deleted: number;
+  epoch: number;
+}
+
+export interface RvfCompactionResult {
+  segmentsCompacted: number;
+  bytesReclaimed: number;
+  epoch: number;
+}
+
+export interface RvfStatus {
+  totalVectors: number;
+  totalSegments: number;
+  fileSize: number;
+  currentEpoch: number;
+  profileId: number;
+  compactionState: string;
+  deadSpaceRatio: number;
+  readOnly: boolean;
+}
+
+export interface RvfMetadataEntry {
+  fieldId: number;
+  valueType: string;
+  value: string;
+}
+
+export interface RvfKernelData {
+  header: Buffer;
+  image: Buffer;
+}
+
+export interface RvfEbpfData {
+  header: Buffer;
+  payload: Buffer;
+}
+
+export interface RvfSegmentInfo {
+  id: number;
+  offset: number;
+  payloadLength: number;
+  segType: string;
+}
+
+export class RvfDatabase {
+  static create(path: string, options: RvfOptions): RvfDatabase;
+  static open(path: string): RvfDatabase;
+  static openReadonly(path: string): RvfDatabase;
+  ingestBatch(vectors: Float32Array, ids: number[], metadata?: RvfMetadataEntry[]): RvfIngestResult;
+  query(vector: Float32Array, k: number, options?: RvfQueryOptions): RvfSearchResult[];
+  delete(ids: number[]): RvfDeleteResult;
+  deleteByFilter(filterJson: string): RvfDeleteResult;
+  compact(): RvfCompactionResult;
+  status(): RvfStatus;
+  close(): void;
+  fileId(): string;
+  parentId(): string;
+  lineageDepth(): number;
+  derive(childPath: string, options?: RvfOptions): RvfDatabase;
+  embedKernel(arch: number, kernelType: number, flags: number, image: Buffer, apiPort: number, cmdline?: string): number;
+  extractKernel(): RvfKernelData | null;
+  embedEbpf(programType: number, attachType: number, maxDimension: number, bytecode: Buffer, btf?: Buffer): number;
+  extractEbpf(): RvfEbpfData | null;
+  segments(): RvfSegmentInfo[];
+  dimension(): number;
+}

package/index.js

@@ -0,0 +1,150 @@
+/* eslint-disable */
+/* auto-generated: NAPI-RS platform loader for @ruvector/rvf-node */
+
+const { existsSync, readFileSync } = require('fs');
+const { join } = require('path');
+
+const { platform, arch } = process;
+
+let nativeBinding = null;
+let localFileExisted = false;
+let loadError = null;
+
+function isMusl() {
+  // For Node 12+, check report.header.glibcVersionRuntime
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process')
+        .execSync('which ldd')
+        .toString()
+        .trim();
+      return readFileSync(lddPath, 'utf8').includes('musl');
+    } catch {
+      return true;
+    }
+  } else {
+    const report = process.report.getReport();
+    const rep = typeof report === 'string' ? JSON.parse(report) : report;
+    return !rep.header.glibcVersionRuntime;
+  }
+}
+
+switch (platform) {
+  case 'darwin':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'rvf-node.darwin-x64.node'));
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rvf-node.darwin-x64.node');
+          } else {
+            nativeBinding = require('@ruvector/rvf-node-darwin-x64');
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'rvf-node.darwin-arm64.node'));
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rvf-node.darwin-arm64.node');
+          } else {
+            nativeBinding = require('@ruvector/rvf-node-darwin-arm64');
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`);
+    }
+    break;
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'rvf-node.win32-x64-msvc.node'));
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./rvf-node.win32-x64-msvc.node');
+          } else {
+            nativeBinding = require('@ruvector/rvf-node-win32-x64-msvc');
+          }
+        } catch (e) {
+          loadError = e;
+        }
+        break;
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`);
+    }
+    break;
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(join(__dirname, 'rvf-node.linux-x64-musl.node'));
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rvf-node.linux-x64-musl.node');
+            } else {
+              nativeBinding = require('@ruvector/rvf-node-linux-x64-musl');
+            }
+          } catch (e) {
+            loadError = e;
+          }
+        } else {
+          localFileExisted = existsSync(join(__dirname, 'rvf-node.linux-x64-gnu.node'));
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rvf-node.linux-x64-gnu.node');
+            } else {
+              nativeBinding = require('@ruvector/rvf-node-linux-x64-gnu');
+            }
+          } catch (e) {
+            loadError = e;
+          }
+        }
+        break;
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(join(__dirname, 'rvf-node.linux-arm64-musl.node'));
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rvf-node.linux-arm64-musl.node');
+            } else {
+              nativeBinding = require('@ruvector/rvf-node-linux-arm64-musl');
+            }
+          } catch (e) {
+            loadError = e;
+          }
+        } else {
+          localFileExisted = existsSync(join(__dirname, 'rvf-node.linux-arm64-gnu.node'));
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./rvf-node.linux-arm64-gnu.node');
+            } else {
+              nativeBinding = require('@ruvector/rvf-node-linux-arm64-gnu');
+            }
+          } catch (e) {
+            loadError = e;
+          }
+        }
+        break;
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`);
+    }
+    break;
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`);
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError;
+  }
+  throw new Error('Failed to load native binding');
+}
+
+const { RvfDatabase } = nativeBinding;
+
+module.exports.RvfDatabase = RvfDatabase;

package/package.json

@@ -1,25 +1,44 @@
 {
   "name": "@ruvector/rvf-node",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "RuVector Format Node.js native bindings",
   "main": "index.js",
   "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
   "napi": {
-    "name": "rvf-node",
-    "triples": {
-      "defaults": true,
-      "additional": [
-        "aarch64-apple-darwin",
-        "aarch64-unknown-linux-gnu"
-      ]
-    }
+    "binaryName": "rvf-node",
+    "targets": [
+      "x86_64-unknown-linux-gnu",
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-pc-windows-msvc",
+      "aarch64-unknown-linux-gnu"
+    ]
   },
   "scripts": {
-    "build": "napi build --platform --release",
-    "test": "jest"
+    "build": "napi build --platform --release"
   },
   "license": "MIT",
-  "devDependencies": {
-    "@napi-rs/cli": "^2.18.0"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ruvnet/ruvector"
+  },
+  "engines": {
+    "node": ">= 16"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@ruvector/rvf-node-linux-x64-gnu": "0.1.4",
+    "@ruvector/rvf-node-darwin-x64": "0.1.4",
+    "@ruvector/rvf-node-darwin-arm64": "0.1.4",
+    "@ruvector/rvf-node-win32-x64-msvc": "0.1.4",
+    "@ruvector/rvf-node-linux-arm64-gnu": "0.1.4"
   }
 }