{"_id":"@aigentic/rvf-node","_rev":"3-fbaf4926af26cd07d00f99b54f63650a","name":"@aigentic/rvf-node","dist-tags":{"latest":"0.1.9"},"versions":{"0.1.8":{"name":"@aigentic/rvf-node","version":"0.1.8","license":"MIT","_id":"@aigentic/rvf-node@0.1.8","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://github.com/ruvnet/ruvector#readme","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"dist":{"shasum":"6bc5985f13fa4978b4a73ed8580983c5b597a4ab","tarball":"https://registry.npmjs.org/@aigentic/rvf-node/-/rvf-node-0.1.8.tgz","fileCount":9,"integrity":"sha512-mEIXd1EJ6tfEpMnC9ffbrAUAr1nEtYuHlAGJhhSukqfbfMRFZNiOsxwmqkW62FHZHeGw7DEa3Xpy5n/1jGfYgQ==","signatures":[{"sig":"MEYCIQDEFQEyC42GYvbbCfkUpWsMn6h0CKmCcdkyDgR751ESAQIhAKq65POlmt0HTE68ACQ71cxRVMmtkTC0YW9u3ZJy6nWK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5440670},"main":"index.js","napi":{"targets":["x86_64-unknown-linux-gnu","x86_64-apple-darwin","aarch64-apple-darwin","x86_64-pc-windows-msvc","aarch64-unknown-linux-gnu"],"binaryName":"rvf-node"},"types":"index.d.ts","engines":{"node":">= 16"},"gitHead":"06426cbc6e70f09762e996a98517b0b1fd1c7c4e","scripts":{"build":"napi build --platform --release"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git"},"_npmVersion":"11.12.0","description":"RuVector Format Node.js native bindings","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"optionalDependencies":{"@aigentic/rvf-node-darwin-x64":"0.1.7","@aigentic/rvf-node-darwin-arm64":"0.1.7","@aigentic/rvf-node-linux-x64-gnu":"0.1.7","@aigentic/rvf-node-win32-x64-msvc":"0.1.7","@aigentic/rvf-node-linux-arm64-gnu":"0.1.7"},"_npmOperationalInternal":{"tmp":"tmp/rvf-node_0.1.8_1779091176446_0.2977934965270759","host":"s3://npm-registry-packages-npm-production"}},"0.1.9":{"name":"@aigentic/rvf-node","version":"0.1.9","license":"MIT","_id":"@aigentic/rvf-node@0.1.9","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://github.com/ruvnet/ruvector#readme","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"dist":{"shasum":"c1a972eb63c20f72d8b54cdf7419ed85479fa7ae","tarball":"https://registry.npmjs.org/@aigentic/rvf-node/-/rvf-node-0.1.9.tgz","fileCount":9,"integrity":"sha512-Pp9bwX2AKSLexXTfr3T15X4T9uLBV0O9E1DwLyDxtgY7dW9EQZKioxa46fNVpZ1aGqnPEeHTAFTC8fjSNjZ4KA==","signatures":[{"sig":"MEYCIQDfgDOaEswueQE8Es6oFhPcRulcXfq3Xt/h44SQCqRq3QIhAN5YvHcVxaKztgSJsZWTJmOLMHblPWBQbO1qmv33I4cC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5440670},"main":"index.js","napi":{"targets":["x86_64-unknown-linux-gnu","x86_64-apple-darwin","aarch64-apple-darwin","x86_64-pc-windows-msvc","aarch64-unknown-linux-gnu"],"binaryName":"rvf-node"},"types":"index.d.ts","engines":{"node":">= 16"},"gitHead":"06426cbc6e70f09762e996a98517b0b1fd1c7c4e","scripts":{"build":"napi build --platform --release"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git"},"_npmVersion":"11.12.0","description":"RuVector Format Node.js native bindings","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"optionalDependencies":{"@aigentic/rvf-node-darwin-x64":"0.1.7","@aigentic/rvf-node-darwin-arm64":"0.1.7","@aigentic/rvf-node-linux-x64-gnu":"0.1.7","@aigentic/rvf-node-win32-x64-msvc":"0.1.7","@aigentic/rvf-node-linux-arm64-gnu":"0.1.7"},"_npmOperationalInternal":{"tmp":"tmp/rvf-node_0.1.9_1779093005428_0.9861200664100174","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-18T07:59:36.365Z","modified":"2026-09-13T15:30:37.068Z","0.1.8":"2026-05-18T07:59:36.664Z","0.1.9":"2026-05-18T08:30:05.693Z"},"bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"license":"MIT","homepage":"https://github.com/ruvnet/ruvector#readme","repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git"},"description":"RuVector Format Node.js native bindings","maintainers":[{"email":"engineering@aigentic.net","name":"aiggy"}],"readme":"# @ruvector/rvf-node\n\nNative 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.\n\n## Install\n\n```bash\nnpm install @ruvector/rvf-node\n```\n\n## Features\n\n- **Native Rust performance** via N-API (napi-rs), no FFI marshaling\n- **Single-file vector database** — crash-safe, no WAL, append-only\n- **k-NN search** with HNSW progressive indexing (recall 0.70 → 0.95)\n- **Metadata filtering** — Eq, Ne, Lt, Gt, Range, In, And, Or, Not\n- **Lineage tracking** — DNA-style parent/child derivation chains\n- **Kernel & eBPF embedding** — embed compute alongside vector data\n- **Segment inspection** — enumerate all segments in the file\n- **Cross-platform** — Linux (x86_64, aarch64), macOS (x86_64, Apple Silicon), Windows (x86_64)\n- **AGI methods** — HNSW index stats, witness chain verification, state freeze, metric introspection\n\n## AGI Methods\n\nFour introspection and integrity methods for advanced use cases.\n\n### `db.indexStats()` → `RvfIndexStats`\n\nReturns HNSW index statistics.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `indexedVectors` | `number` | Number of indexed vectors |\n| `layers` | `number` | Number of HNSW layers |\n| `m` | `number` | M parameter (max edges per node per layer) |\n| `efConstruction` | `number` | ef_construction parameter |\n| `needsRebuild` | `boolean` | Whether index needs rebuilding (dead_space_ratio > 0.3) |\n\n### `db.verifyWitness()` → `RvfWitnessResult`\n\nVerifies SHAKE-256 witness chain integrity.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `valid` | `boolean` | Whether the chain is valid |\n| `entries` | `number` | Number of entries in the chain |\n| `error` | `string?` | Error message if invalid |\n\n### `db.freeze()` → `number`\n\nSnapshot-freeze current state. Returns the epoch number.\n\n### `db.metric()` → `string`\n\nReturns the distance metric name (`\"l2\"`, `\"cosine\"`, or `\"inner_product\"`).\n\n### Usage Example\n\n```javascript\nconst stats = db.indexStats();\nconsole.log(`Indexed: ${stats.indexedVectors}, HNSW layers: ${stats.layers}`);\n\nconst witness = db.verifyWitness();\nconsole.log(`Witness chain: ${witness.entries} entries, valid: ${witness.valid}`);\n\nconsole.log(`Distance metric: ${db.metric()}`);\n\nconst epoch = db.freeze();\nconsole.log(`State frozen at epoch ${epoch}`);\n```\n\n## Quick Start\n\n```javascript\nconst { RvfDatabase } = require('@ruvector/rvf-node');\n\n// Create a store\nconst db = RvfDatabase.create('vectors.rvf', {\n  dimension: 384,\n  metric: 'cosine',\n});\n\n// Insert vectors\nconst vectors = new Float32Array(384 * 2); // 2 vectors, 384 dims each\nvectors.fill(0.1);\ndb.ingestBatch(vectors, [1, 2]);\n\n// Query nearest neighbors\nconst query = new Float32Array(384);\nquery.fill(0.15);\nconst results = db.query(query, 5);\n// [{ id: 1, distance: 0.002 }, { id: 2, distance: 0.002 }]\n\ndb.close();\n```\n\n## API Reference\n\n### Store Lifecycle\n\n```typescript\n// Create a new store\nconst db = RvfDatabase.create(path: string, options: RvfOptions);\n\n// Open existing store (read-write, acquires writer lock)\nconst db = RvfDatabase.open(path: string);\n\n// Open read-only (no lock, concurrent readers allowed)\nconst db = RvfDatabase.openReadonly(path: string);\n\n// Close and flush\ndb.close();\n```\n\n**RvfOptions:**\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `dimension` | `number` | required | Vector dimensionality |\n| `metric` | `string` | `\"l2\"` | `\"l2\"`, `\"cosine\"`, or `\"inner_product\"` |\n| `profile` | `number` | `0` | Hardware profile: 0=Generic, 1=Core, 2=Hot, 3=Full |\n| `signing` | `boolean` | `false` | Enable segment signing |\n| `m` | `number` | `16` | HNSW M parameter (neighbor count) |\n| `efConstruction` | `number` | `200` | HNSW index build quality |\n\n### Ingest Vectors\n\n```typescript\nconst result = db.ingestBatch(\n  vectors: Float32Array,  // flat array of n * dimension floats\n  ids: number[],          // vector IDs\n  metadata?: RvfMetadataEntry[]  // optional metadata per vector\n);\n// Returns: { accepted: number, rejected: number, epoch: number }\n```\n\n**Metadata entry format:**\n\n```typescript\n{ fieldId: 0, valueType: 'string', value: 'category_a' }\n{ fieldId: 1, valueType: 'f64',    value: '0.95' }\n{ fieldId: 2, valueType: 'u64',    value: '42' }\n```\n\n### Query\n\n```typescript\nconst results = db.query(\n  vector: Float32Array,      // query vector\n  k: number,                 // number of neighbors\n  options?: RvfQueryOptions   // optional search parameters\n);\n// Returns: [{ id: number, distance: number }, ...]\n```\n\n**RvfQueryOptions:**\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `efSearch` | `number` | `100` | HNSW search quality (higher = better recall, slower) |\n| `filter` | `string` | — | Filter expression as JSON string |\n| `timeoutMs` | `number` | `0` | Query timeout in ms (0 = no timeout) |\n\n### Filter Expressions\n\nFilters are passed as JSON strings. All leaf filters require `fieldId`, `valueType`, and `value`:\n\n```javascript\n// Equality\ndb.query(vec, 10, {\n  filter: '{\"op\":\"eq\",\"fieldId\":0,\"valueType\":\"string\",\"value\":\"science\"}'\n});\n\n// Range\ndb.query(vec, 10, {\n  filter: '{\"op\":\"range\",\"fieldId\":1,\"valueType\":\"f64\",\"low\":\"0.5\",\"high\":\"1.0\"}'\n});\n\n// In-set\ndb.query(vec, 10, {\n  filter: '{\"op\":\"in\",\"fieldId\":0,\"valueType\":\"u64\",\"values\":[\"1\",\"2\",\"5\"]}'\n});\n\n// Boolean combinations\ndb.query(vec, 10, {\n  filter: JSON.stringify({\n    op: 'and',\n    children: [\n      { op: 'eq', fieldId: 0, valueType: 'string', value: 'science' },\n      { op: 'gt', fieldId: 1, valueType: 'f64', value: '0.8' }\n    ]\n  })\n});\n\n// Negation\ndb.query(vec, 10, {\n  filter: '{\"op\":\"not\",\"child\":{\"op\":\"eq\",\"fieldId\":0,\"valueType\":\"string\",\"value\":\"spam\"}}'\n});\n```\n\n**Supported operators:** `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `in`, `range`, `and`, `or`, `not`\n\n**Supported value types:** `u64`, `i64`, `f64`, `string`, `bool`\n\n### Delete\n\n```typescript\n// Delete by ID\nconst result = db.delete([1, 2, 3]);\n// Returns: { deleted: number, epoch: number }\n\n// Delete by filter\nconst result = db.deleteByFilter(\n  '{\"op\":\"gt\",\"fieldId\":1,\"valueType\":\"f64\",\"value\":\"0.9\"}'\n);\n```\n\n### Compact\n\nReclaims space from deleted vectors:\n\n```typescript\nconst result = db.compact();\n// Returns: { segmentsCompacted: number, bytesReclaimed: number, epoch: number }\n```\n\n### Status\n\n```typescript\nconst status = db.status();\n// {\n//   totalVectors: number,\n//   totalSegments: number,\n//   fileSize: number,\n//   currentEpoch: number,\n//   profileId: number,\n//   compactionState: 'idle' | 'running' | 'emergency',\n//   deadSpaceRatio: number,\n//   readOnly: boolean\n// }\n```\n\n### Lineage & Derivation\n\nRVF tracks parent/child relationships with cryptographic hashes:\n\n```typescript\ndb.fileId();        // hex string — unique file identifier\ndb.parentId();      // hex string — parent's ID (zeros if root)\ndb.lineageDepth();  // 0 for root files\n\n// Derive a child store (inherits dimensions and options)\nconst child = db.derive('/tmp/child.rvf');\nchild.lineageDepth(); // 1\nchild.parentId();     // matches parent's fileId()\n```\n\n### Kernel & eBPF Embedding\n\nEmbed compute segments alongside vector data:\n\n```typescript\n// Embed a Linux microkernel\ndb.embedKernel(\n  1,                           // arch: 0=x86_64, 1=aarch64\n  0,                           // kernel type\n  0,                           // flags\n  Buffer.from(kernelImage),    // kernel binary\n  8080,                        // API port\n  'console=ttyS0 quiet'       // kernel cmdline (optional)\n);\n\n// Extract kernel\nconst kernel = db.extractKernel();\nif (kernel) {\n  console.log(kernel.header);  // Buffer: 128-byte KernelHeader\n  console.log(kernel.image);   // Buffer: kernel image bytes\n}\n\n// Embed an eBPF XDP program\ndb.embedEbpf(\n  1,                          // program type (XDP distance)\n  2,                          // attach type (XDP ingress)\n  384,                        // max vector dimension\n  Buffer.from(bytecode),      // BPF ELF object\n  Buffer.from(btf)            // optional BTF section\n);\n\n// Extract eBPF\nconst ebpf = db.extractEbpf();\nif (ebpf) {\n  console.log(ebpf.header);   // Buffer: 64-byte EbpfHeader\n  console.log(ebpf.payload);  // Buffer: bytecode + BTF\n}\n```\n\n### Segment Inspection\n\n```typescript\nconst segments = db.segments();\n// [{ id: 1, offset: 0, payloadLength: 4096, segType: 'manifest' },\n//  { id: 2, offset: 4160, payloadLength: 51200, segType: 'vec' },\n//  { id: 3, offset: 55424, payloadLength: 12288, segType: 'index' }]\n\ndb.dimension(); // 384\n```\n\n## Self-Booting RVF\n\nAn `.rvf` file can embed a Linux kernel, eBPF programs, and SSH keys alongside vector data — producing a single file that boots as a microservice.\n\nThe Claude Code Appliance example builds a complete AI dev environment:\n\n```bash\ncd examples/rvf\ncargo run --example claude_code_appliance\n```\n\n```\nclaude_code_appliance.rvf\n  ├── KERNEL_SEG    Linux 6.8.12 bzImage (5.2 MB, x86_64)\n  ├── EBPF_SEG      Socket filter — ports 2222, 8080 only\n  ├── VEC_SEG       20 package embeddings (128-dim)\n  ├── INDEX_SEG     HNSW graph for package search\n  ├── WITNESS_SEG   6-entry tamper-evident audit trail\n  └── CRYPTO_SEG    3 Ed25519 SSH user keys\n```\n\nFinal file: **5.1 MB single `.rvf`** — boots Linux, serves queries, runs Claude Code.\n\nSee the [full RVF documentation](https://github.com/ruvnet/ruvector/tree/main/crates/rvf) for details.\n\n## Build from Source\n\n```bash\n# Prerequisites: Rust 1.87+, Node.js 18+\ncd crates/rvf/rvf-node\nnpm install\nnpm run build\n```\n\n## Related Packages\n\n| Package | Description |\n|---------|-------------|\n| [`@ruvector/rvf`](https://www.npmjs.com/package/@ruvector/rvf) | Unified TypeScript SDK |\n| [`@ruvector/rvf-wasm`](https://www.npmjs.com/package/@ruvector/rvf-wasm) | Browser WASM package |\n| [`@ruvector/rvf-mcp-server`](https://www.npmjs.com/package/@ruvector/rvf-mcp-server) | MCP server for AI agents |\n| [`rvf-runtime`](https://crates.io/crates/rvf-runtime) | Rust runtime (powers this package) |\n\n## License\n\nMIT OR Apache-2.0\n","readmeFilename":"README.md"}