feat: expose Rust CowEngine through rvf_branch and rvf_freeze MCP tools

[vRobM]

Summary

Exposes the existing Rust CowEngine (crates/rvf/rvf-runtime/src/cow.rs + store.rs) through MCP tools. The Rust crate already has production COW branching with cluster-based COW addressing, dual-graph ANN query merge, membership-based tombstones, and witness audit — but it was only accessible via the NAPI RvfDatabase.branch() method with no MCP tool surface.

What Changed

npm/packages/ruvector/src/core/rvf-wrapper.ts — added two wrappers:

• rvfBranch(store, childPath) — calls store.branch() which invokes the Rust CowEngine::from_parent() + MembershipFilter initialization. The child inherits all parent vectors with cluster-based COW; writes only allocate local clusters (≈162 B per branch, independent of parent size).
• rvfFreeze(store) — calls store.freeze() which sets read_only = true and freezes the CowEngine epoch, preventing further writes.

npm/packages/ruvector/bin/mcp-server.js — added two MCP tools:

• rvf_branch — create a full COW branch. Queries the child return parent ∪ child-edits via dual-graph ANN merge (query_via_index_cow()). Re-ingested vectors override parent on id collision; deletes in the child hide inherited vectors via MembershipFilter. The parent should be frozen first (rvf_freeze) for production data.
• rvf_freeze — snapshot-freeze a store. Prevents writes, freezes CowEngine epoch.

Also updated rvf_derive description to clarify it is lineage-only (records parent hash + depth, no COW — child cannot see parent vectors).

npm/packages/ruvector/bin/cli.js — updated help text.

Architecture

MCP tool (rvf_branch)
  → mcp-server.js handler
    → rvf-wrapper.ts (rvfBranch)
      → @ruvector/rvf NAPI (store.branch())
        → Rust RvfStore::branch() (store.rs:2194)
          → CowEngine::from_parent() (cow.rs) — cluster-based COW
          → MembershipFilter — all parent vectors visible at query time
          → Dual-graph ANN query merge for read-through

The Rust COW engine (fully in crates/rvf/rvf-runtime/src/):

• CowEngine (cow.rs): cluster-based COW, read_vector()/write_vector() with parent chain resolution, flush_writes() for slab copy-on-write, freeze(epoch) for snapshot
• RvfStore::branch() (store.rs:2194): creates COW child with derive() + CowEngine::from_parent() + MembershipFilter seeded with all parent vectors
• query_via_index_cow() (store.rs:614): dual-graph ANN merge — queries child + parent HNSW simultaneously, child-wins on id collision, tombstone filtering
• MembershipFilter: tombstoning parent IDs when a COW child deletes

Testing

These wrappers call through to the existing NAPI bindings which are integration-tested in crates/rvf/tests/. No changes to the Rust crate itself — purely an MCP surface addition.

Files Changed

npm/packages/ruvector/src/core/rvf-wrapper.ts  | +22  (rvfBranch, rvfFreeze wrappers)
npm/packages/ruvector/bin/mcp-server.js        | +56  (tool registrations + handlers)
npm/packages/ruvector/bin/cli.js               |  +6  (help text)