Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

2026-02-28 14:39:40 -05:00
parent 7885bf6278 d803bfe2b1
commit cd5943df23
7854 changed files with 3522914 additions and 0 deletions
--- a/vendor/ruvector/crates/ruvector-graph-transformer-node/README.md
+++ b/vendor/ruvector/crates/ruvector-graph-transformer-node/README.md
@@ -0,0 +1,235 @@
+# @ruvector/graph-transformer
+
+[![npm](https://img.shields.io/npm/v/@ruvector/graph-transformer.svg)](https://www.npmjs.com/package/@ruvector/graph-transformer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-20_passing-brightgreen.svg)]()
+
+**Node.js bindings for RuVector Graph Transformer — proof-gated graph attention, verified training, and 8 specialized graph layers via NAPI-RS.**
+
+Use graph transformers from JavaScript and TypeScript with native Rust performance. Every graph operation — adding nodes, computing attention, training weights — produces a formal proof receipt proving it was done correctly. The heavy computation runs in compiled Rust via NAPI-RS, so you get sub-millisecond proof verification without leaving the Node.js ecosystem.
+
+## Install
+
+```bash
+npm install @ruvector/graph-transformer
+```
+
+Prebuilt binaries are provided for:
+
+| Platform | Architecture | Package |
+|----------|-------------|---------|
+| Linux | x64 (glibc) | `@ruvector/graph-transformer-linux-x64-gnu` |
+| Linux | x64 (musl) | `@ruvector/graph-transformer-linux-x64-musl` |
+| Linux | ARM64 (glibc) | `@ruvector/graph-transformer-linux-arm64-gnu` |
+| macOS | x64 (Intel) | `@ruvector/graph-transformer-darwin-x64` |
+| macOS | ARM64 (Apple Silicon) | `@ruvector/graph-transformer-darwin-arm64` |
+| Windows | x64 | `@ruvector/graph-transformer-win32-x64-msvc` |
+
+## Quick Start
+
+```javascript
+const { GraphTransformer } = require('@ruvector/graph-transformer');
+
+const gt = new GraphTransformer();
+console.log(gt.version()); // "2.0.4"
+
+// Proof-gated mutation
+const gate = gt.createProofGate(128);
+console.log(gate.dimension); // 128
+
+// Prove dimension equality
+const proof = gt.proveDimension(128, 128);
+console.log(proof.verified); // true
+
+// Create attestation (82-byte proof receipt)
+const attestation = gt.createAttestation(proof.proof_id);
+console.log(attestation.length); // 82
+```
+
+## API Reference
+
+### Proof-Gated Operations
+
+```javascript
+// Create a proof gate for a dimension
+const gate = gt.createProofGate(dim);
+
+// Prove two dimensions are equal
+const proof = gt.proveDimension(expected, actual);
+
+// Create 82-byte attestation for embedding in RVF witness chains
+const bytes = gt.createAttestation(proofId);
+
+// Verify attestation from bytes
+const valid = gt.verifyAttestation(bytes);
+
+// Compose a pipeline of type-checked stages
+const composed = gt.composeProofs([
+  { name: 'embed', input_type_id: 1, output_type_id: 2 },
+  { name: 'align', input_type_id: 2, output_type_id: 3 },
+]);
+```
+
+### Sublinear Attention
+
+```javascript
+// O(n log n) graph attention via PPR sparsification
+const result = gt.sublinearAttention(
+  [1.0, 0.5, -0.3],     // query vector
+  [[1, 2], [0, 2], [0, 1]], // adjacency list
+  3,                      // dimension
+  2                       // top-k
+);
+console.log(result.top_k_indices, result.sparsity_ratio);
+
+// Raw PPR scores
+const scores = gt.pprScores(0, [[1], [0, 2], [1]], 0.15);
+```
+
+### Physics-Informed Layers
+
+```javascript
+// Symplectic leapfrog step (energy-conserving)
+const state = gt.hamiltonianStep([1.0, 0.0], [0.0, 1.0], 0.01);
+console.log(state.energy);
+
+// With graph interactions
+const state2 = gt.hamiltonianStepGraph(
+  [1.0, 0.0], [0.0, 1.0],
+  [{ src: 0, tgt: 1 }], 0.01
+);
+console.log(state2.energy_conserved); // true
+```
+
+### Biological Layers
+
+```javascript
+// Spiking neural attention (event-driven)
+const output = gt.spikingAttention(
+  [0.5, 1.5, 0.3],          // membrane potentials
+  [[1], [0, 2], [1]],       // adjacency
+  1.0                        // firing threshold
+);
+
+// Hebbian weight update (Hebb's rule)
+const weights = gt.hebbianUpdate(
+  [1.0, 0.0],  // pre-synaptic
+  [0.0, 1.0],  // post-synaptic
+  [0, 0, 0, 0], // current weights (flattened)
+  0.1            // learning rate
+);
+
+// Full spiking step over feature matrix
+const result = gt.spikingStep(
+  [[0.8, 0.6], [0.1, 0.2]],  // n x dim features
+  [0, 0.5, 0.3, 0]            // flat adjacency (n x n)
+);
+```
+
+### Verified Training
+
+```javascript
+// Single verified SGD step with proof receipt
+const result = gt.verifiedStep(
+  [1.0, 2.0],  // weights
+  [0.1, 0.2],  // gradients
+  0.01          // learning rate
+);
+console.log(result.proof_id, result.loss_before, result.loss_after);
+
+// Full training step with features and targets
+const step = gt.verifiedTrainingStep(
+  [1.0, 2.0],   // features
+  [0.5, 1.0],   // targets
+  [0.5, 0.5]    // weights
+);
+console.log(step.certificate_id, step.loss);
+```
+
+### Manifold Operations
+
+```javascript
+// Product manifold distance (mixed curvatures)
+const d = gt.productManifoldDistance(
+  [1, 0, 0, 1],    // point a
+  [0, 1, 1, 0],    // point b
+  [0.0, -1.0]      // curvatures (Euclidean, Hyperbolic)
+);
+
+// Product manifold attention
+const result = gt.productManifoldAttention(
+  [1.0, 0.5, -0.3, 0.8],
+  [{ src: 0, tgt: 1 }]
+);
+```
+
+### Temporal-Causal Attention
+
+```javascript
+// Causal attention (no future information leakage)
+const scores = gt.causalAttention(
+  [1.0, 0.0],                        // query
+  [[1.0, 0.0], [0.0, 1.0], [0.5, 0.5]], // keys
+  [1.0, 2.0, 3.0]                    // timestamps
+);
+
+// Causal attention over graph
+const output = gt.causalAttentionGraph(
+  [1.0, 0.5, 0.8],    // node features
+  [1.0, 2.0, 3.0],    // timestamps
+  [{ src: 0, tgt: 1 }, { src: 1, tgt: 2 }]
+);
+
+// Granger causality extraction
+const dag = gt.grangerExtract(flatHistory, 3, 20);
+console.log(dag.edges); // [{ source, target, f_statistic, is_causal }]
+```
+
+### Economic / Game-Theoretic
+
+```javascript
+// Nash equilibrium attention
+const result = gt.gameTheoreticAttention(
+  [1.0, 0.5, 0.8],  // utility values
+  [{ src: 0, tgt: 1 }, { src: 1, tgt: 2 }]
+);
+console.log(result.allocations, result.nash_gap, result.converged);
+```
+
+### Stats & Control
+
+```javascript
+// Aggregate statistics
+const stats = gt.stats();
+console.log(stats.proofs_verified, stats.attestations_created);
+
+// Reset all internal state
+gt.reset();
+```
+
+## Building from Source
+
+```bash
+# Install NAPI-RS CLI
+npm install -g @napi-rs/cli
+
+# Build native module
+cd crates/ruvector-graph-transformer-node
+napi build --platform --release
+
+# Run tests
+cargo test -p ruvector-graph-transformer-node
+```
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`ruvector-graph-transformer`](../ruvector-graph-transformer) | Core Rust crate |
+| [`ruvector-graph-transformer-wasm`](../ruvector-graph-transformer-wasm) | WASM bindings for browsers |
+| [`@ruvector/gnn`](https://www.npmjs.com/package/@ruvector/gnn) | Base GNN operations |
+| [`@ruvector/attention`](https://www.npmjs.com/package/@ruvector/attention) | 46 attention mechanisms |
+
+## License
+
+MIT