ADR-032: RVF WASM Integration into npx ruvector and rvlite

[ruvnet]

Summary

Integrate @ruvector/rvf (and its WASM backend) into npx ruvector and rvlite packages per ADR-032.

Key Invariants

1. Single writer rule -- One writer lease per store (file lock on Node, heartbeat on browser). Readers unlimited.
2. Crash ordering -- RVF is source of truth. IndexedDB is rebuildable cache. Epoch reconciliation on startup.
3. Backend selection -- Explicit --backend rvf never silently falls back. Fail loud with install hint.
4. Cross-platform compat -- WASM-written files readable by Node and vice versa for same RVF version.

Phase 1: npx ruvector

• Add @ruvector/rvf as optional dependency
• Create rvf-wrapper.ts matching existing core interface
• Add rvf CLI command group (create, ingest, query, status, segments, derive, compact, export)
• Add rvf examples and rvf download CLI commands (45 example files)
• Add 10 RVF tools to main MCP server
• Add hooks --backend rvf flag (explicit selection, no silent fallback)
• Smoke test: 4 Rust integration tests (full lifecycle, cosine, multi-restart, metadata)
• Error messages include install command for missing packages

Phase 1 Security Hardening

• Path traversal protection in rvf download (filename sanitization + containment)
• SSRF protection (redirect host whitelist)
• Path validation for all 9 RVF MCP tool handlers (validateRvfPath)
• Command injection mitigation (sanitizeShellArg on 25+ execSync handlers)
• Numeric argument validation (parseInt with defaults)

Phase 2: rvlite

• Feature-flag rvf-backend in Rust crate (default unchanged)
• Epoch reconciliation module (storage/epoch.rs) — 23 tests, EpochTracker with AtomicU64, thread-safe
• Auto-detect @ruvector/rvf-wasm with isRvfAvailable() / getStorageBackend()
• Cypher injection prevention (sanitizeCypher, validateRelationType)
• Full epoch reconciliation algorithm (begin_write → commit → check_and_reconcile)
• rvf-migrate CLI with --dry-run and --verify modes (idempotent, 1e-6 tolerance)
• rvf-rebuild to reconstruct metadata from RVF
• Writer lease — Rust: WriterLease with file lock + PID stale detection (12 tests); JS: BrowserWriterLease with IndexedDB heartbeat
• Direct ID mapping: IdMapping trait, DirectIdMap (identity), OffsetIdMap (20 tests)
• TypeScript SDK: createWithRvf(), saveToRvf(), loadFromRvf(), RvfFileEnvelope fallback format

Phase 3: Shared WASM

• @ruvector/rvf-wasm as shared optional peer dependency in rvlite
• CI build step (wasm-dedup-check.yml) fails if duplicate WASM artifacts detected
• 3 MCP server rvlite tools (rvlite_sql, rvlite_cypher, rvlite_sparql) — read-only default
• Cross-platform compatibility tests: 6 tests (cosine/L2/IP round-trip, segment preservation, byte-identical)

Test Results

Suite	Tests	Status
Rust storage (epoch + writer_lease + id_map)	55 passed + 2 doc	All pass
RVF smoke test	4 passed	All pass
RVF cross-platform compat	6 passed	All pass
RVF integration (lifecycle + lineage)	16 passed	All pass
TypeScript transpilation	2 files	Clean
JS syntax	3 files	Clean

Documentation

• @ruvector/rvf README: complete rewrite (342 lines) — platform matrix, segments, API, examples
• ruvector README: +89 lines — RVF section with CLI commands and platform table
• rvlite README: +61 lines — RVF storage backend, epoch reconciliation, downloads

Failure Modes to Test

#	Scenario	Expected
1	Power loss during ingest	Last committed epoch consistent
2	Crash between RVF and metadata write	Epoch reconciliation self-heals
3	Two writers on same store	Second gets ELOCK error
4	Migration rerun	No-op, no duplication
5	Node write → browser read → browser write → Node read	Results match within 1e-6
6	Browser refresh during write	Lease expires, next open acquires fresh

Acceptance Test

Clean machine: create → ingest → query → restart twice → migrate rvlite store → open in browser → top-10 neighbors match Node results within 1e-6 tolerance.

Related

• ADR-030: RVF Cognitive Container
• ADR-031: RVCOW Branching
• Branch: claude/ruvector-format-design-a8JSi

[ruvnet]

Phase 1 Implementation Progress + Security Hardening

Completed (Phase 1)

npx ruvector:

• @ruvector/rvf optional dependency + 3-tier platform detection (native → rvf → stub)
• rvf-wrapper.ts — 10 RVF functions matching core interface
• 8 rvf CLI commands: create, ingest, query, status, segments, derive, compact, export
• 2 new CLI commands: rvf examples (lists 45 files), rvf download (fetches from GitHub)
• 10 RVF tools added to main MCP server (rvf_create through rvf_examples)
• mcp info updated to show RVF tools section
• Error messages include install hints for missing packages

rvlite:

• rvf-backend feature flag in Rust crate (crates/rvlite/Cargo.toml)
• Epoch reconciliation module (crates/rvlite/src/storage/epoch.rs)
• isRvfAvailable() and getStorageBackend() TypeScript exports
• createRvLite() factory auto-detects backend (rvf → indexeddb → memory)
• @ruvector/rvf-wasm as optional dependency in package.json

Documentation:

• @ruvector/rvf README complete rewrite (60 → 342 lines): platform matrix, 20 segments, 19 N-API methods, 29 WASM exports, 45 example catalog
• ruvector README: +89 lines with RVF section, 8 CLI commands, platform table
• rvlite README: +61 lines with RVF storage backend section, epoch reconciliation

Security Hardening (9 vulnerabilities fixed)

Sev	Surface	Issue	Fix
CRITICAL	CLI download	Path traversal via filenames	sanitizeFileName() + allowlist + containment
CRITICAL	MCP server	Command injection via execSync	sanitizeShellArg() on all 25+ handlers
HIGH	MCP rvf_* tools	Path traversal via args.path	validateRvfPath() blocks .., system paths
HIGH	CLI download	SSRF via redirect	ALLOWED_REDIRECT_HOSTS whitelist
HIGH	CLI download	URL injection	encodeURIComponent() on filenames
MEDIUM	rvlite	Cypher injection	sanitizeCypher() escapes quotes/control chars
MEDIUM	rvlite	Arbitrary relation types	validateRelationType() restricts to [A-Za-z_]\w*
MEDIUM	MCP hooks	Numeric arg injection	parseInt() with fallback defaults
MEDIUM	rvlite	Graph depth abuse	findRelated() depth clamped to [1, 10]

Diff Summary

6 files changed, 1036 insertions(+), 46 deletions(-)

Remaining (Phase 1)

• End-to-end smoke test: create → ingest → query → restart → query

Remaining (Phase 2)

• Full epoch reconciliation algorithm
• rvf-migrate and rvf-rebuild CLI commands
• Writer lease (file lock + heartbeat)

Remaining (Phase 3)

• Shared WASM deduplication
• CI duplicate check
• Cross-platform compat matrix

ADR-032 updated with security hardening section and checked implementation items.

[ruvnet]

All three phases complete. Summary:

Phase 1 (npx ruvector): 8 CLI commands, 10 MCP tools, security hardening (9 vulns fixed), 4 smoke tests passing.

Phase 2 (rvlite): Full epoch reconciliation (23 tests), writer lease with file lock + browser heartbeat (12 tests), direct ID mapping (20 tests), rvf-migrate + rvf-rebuild CLI commands, TypeScript SDK with createWithRvf/saveToRvf/loadFromRvf.

Phase 3 (Shared WASM): CI dedup check, 3 MCP rvlite tools (read-only default), 6 cross-platform compat tests, shared peer dependency.

Total: 81 new Rust tests passing, 2 new TypeScript modules, 1 CI workflow. Branch: claude/ruvector-format-design-a8JSi.