wifi-densepose/docs/adr/ADR-050-graph-transformer-bindings.md

# ADR-050: Graph Transformer WASM and Node.js Bindings

## Status

Accepted

## Date

2026-02-25

## Context

RuVector's existing crates ship WASM and Node.js bindings following a consistent pattern: a `-wasm` crate using `wasm-bindgen` and a `-node` crate using `napi-rs`. Examples include `ruvector-gnn-wasm` / `ruvector-gnn-node`, `ruvector-graph-wasm` / `ruvector-graph-node`, `ruvector-verified-wasm`, and `ruvector-mincut-wasm` / `ruvector-mincut-node`.

The new `ruvector-graph-transformer` crate (ADR-046) needs equivalent bindings so that TypeScript/JavaScript applications can use proof-gated graph transformers in the browser (WASM) and on the server (Node.js via NAPI-RS). The challenge is deciding which subset of the Rust API to expose, managing the WASM binary size (target < 300 KB), and ensuring feature parity where feasible.

### Existing Binding Patterns

From `crates/ruvector-gnn-wasm/Cargo.toml`:
- `crate-type = ["cdylib", "rlib"]`
- Dependencies: `ruvector-gnn` with `default-features = false, features = ["wasm"]`
- Uses `serde-wasm-bindgen = "0.6"` for struct serialization
- Release profile: `opt-level = "z"`, `lto = true`, `codegen-units = 1`, `panic = "abort"`

From `crates/ruvector-gnn-node/Cargo.toml`:
- `crate-type = ["cdylib"]`
- Dependencies: `napi = { workspace = true }`, `napi-derive = { workspace = true }`
- Build dependency: `napi-build = "2"`
- Release profile: `lto = true`, `strip = true`

From `crates/ruvector-verified-wasm/Cargo.toml`:
- Dependencies: `ruvector-verified` with `features = ["ultra"]`
- Uses `wasm-bindgen`, `serde-wasm-bindgen`, `js-sys`, `web-sys`
- Release profile: `opt-level = "s"`, `lto = true`

## Decision

We will create two binding crates following the established workspace patterns:

- `crates/ruvector-graph-transformer-wasm/` -- WASM bindings via `wasm-bindgen`
- `crates/ruvector-graph-transformer-node/` -- Node.js bindings via `napi-rs` (v2.16)

### API Surface: What to Expose

Not all Rust functionality translates efficiently to WASM/JS. The binding surface is scoped to three tiers:

**Tier 1 -- Core (both WASM and Node.js)**:
| API | Rust Source | Binding |
|-----|------------|---------|
| `GraphTransformer::new(config)` | `lib.rs` | Constructor, takes JSON config |
| `GraphTransformer::forward(batch)` | `lib.rs` | Returns `ProofGatedOutput` as JSON |
| `GraphTransformer::mutate(op)` | `lib.rs` | Returns mutation result + attestation |
| `ProofGate::unlock()` | `proof_gated/gate.rs` | Unlocks and returns inner value |
| `ProofGate::is_satisfied()` | `proof_gated/gate.rs` | Boolean check |
| `proof_chain()` | `proof_gated/mod.rs` | Returns attestation array as `Uint8Array[]` |
| `coherence()` | via `ruvector-coherence` | Returns coherence snapshot as JSON |

**Tier 2 -- Attention (both WASM and Node.js)**:
| API | Rust Source | Binding |
|-----|------------|---------|
| `PprSampledAttention::new()` | `sublinear_attention/ppr.rs` | Constructor |
| `LshSpectralAttention::new()` | `sublinear_attention/lsh.rs` | Constructor |
| `certify_complexity()` | `sublinear_attention/mod.rs` | Returns complexity bound as JSON |
| `SpectralSparsifier::sparsify()` | `sublinear_attention/spectral_sparsify.rs` | Returns sparsified edge list |

**Tier 3 -- Training (Node.js only, not WASM)**:
| API | Rust Source | Binding |
|-----|------------|---------|
| `VerifiedTrainer::new(config)` | `verified_training/pipeline.rs` | Constructor |
| `VerifiedTrainer::step()` | `verified_training/pipeline.rs` | Single training step |
| `VerifiedTrainer::seal()` | `verified_training/pipeline.rs` | Returns `TrainingCertificate` as JSON |
| `RobustnessCertifier::certify()` | `verified_training/mod.rs` | Returns certificate as JSON |

Training is excluded from WASM because:
1. Training requires `rayon` for parallelism (not available in WASM)
2. `ElasticWeightConsolidation` uses `ndarray` with BLAS, which adds ~500 KB to WASM size
3. Training workloads are server-side; inference is the browser use case

### WASM Crate Structure

```
crates/ruvector-graph-transformer-wasm/
  Cargo.toml
  src/
    lib.rs              # wasm_bindgen entry points
    types.rs            # TS-friendly wrapper types (JsValue serialization)
    proof_gate.rs       # ProofGate WASM bindings
    attention.rs        # Sublinear attention WASM bindings
    error.rs            # Error conversion to JsValue
  tests/
    web.rs              # wasm-bindgen-test integration tests
  package.json          # npm package metadata
  tsconfig.json         # TypeScript configuration for generated types
```

```toml
# Cargo.toml
[package]
name = "ruvector-graph-transformer-wasm"
version = "2.0.4"
edition = "2021"
rust-version = "1.77"
license = "MIT"
description = "WASM bindings for ruvector-graph-transformer: proof-gated graph transformers in the browser"

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
ruvector-graph-transformer = { version = "2.0.4", path = "../ruvector-graph-transformer",
    default-features = false,
    features = ["proof-gated", "sublinear-attention"] }
wasm-bindgen = { workspace = true }
serde-wasm-bindgen = "0.6"
serde = { workspace = true, features = ["derive"] }
serde_json = { workspace = true }
js-sys = { workspace = true }
web-sys = { workspace = true, features = ["console"] }
getrandom = { workspace = true, features = ["wasm_js"] }

[dev-dependencies]
wasm-bindgen-test = "0.3"

[profile.release]
opt-level = "z"
lto = true
codegen-units = 1
panic = "abort"

[profile.release.package."*"]
opt-level = "z"
```

### WASM Binding Implementation

```rust
// src/lib.rs
use wasm_bindgen::prelude::*;
use ruvector_graph_transformer::{GraphTransformer, GraphTransformerConfig};

#[wasm_bindgen]
pub struct WasmGraphTransformer {
    inner: GraphTransformer,
}

#[wasm_bindgen]
impl WasmGraphTransformer {
    /// Create a new graph transformer from JSON config.
    #[wasm_bindgen(constructor)]
    pub fn new(config_json: &str) -> Result<WasmGraphTransformer, JsValue> {
        let config: GraphTransformerConfig = serde_json::from_str(config_json)
            .map_err(|e| JsValue::from_str(&e.to_string()))?;
        let inner = GraphTransformer::new(config, DefaultPropertyGraph::new())
            .map_err(|e| JsValue::from_str(&e.to_string()))?;
        Ok(Self { inner })
    }

    /// Run forward pass. Input and output are JSON-serialized.
    pub fn forward(&mut self, batch_json: &str) -> Result<JsValue, JsValue> {
        // Deserialize, run forward, serialize result
        // ...
    }

    /// Get the proof attestation chain as an array of Uint8Arrays.
    pub fn proof_chain(&self) -> Result<JsValue, JsValue> {
        let chain = self.inner.proof_chain();
        let array = js_sys::Array::new();
        for att in chain {
            let bytes = att.to_bytes();
            let uint8 = js_sys::Uint8Array::from(&bytes[..]);
            array.push(&uint8);
        }
        Ok(array.into())
    }

    /// Get coherence snapshot as JSON.
    pub fn coherence(&self) -> Result<String, JsValue> {
        let snapshot = self.inner.coherence();
        serde_json::to_string(&snapshot)
            .map_err(|e| JsValue::from_str(&e.to_string()))
    }
}
```

### Node.js Crate Structure

```
crates/ruvector-graph-transformer-node/
  Cargo.toml
  src/
    lib.rs              # napi-rs entry points
    types.rs            # NAPI-RS type wrappers
    proof_gate.rs       # ProofGate Node bindings
    attention.rs        # Sublinear attention Node bindings
    training.rs         # VerifiedTrainer Node bindings (Tier 3)
  build.rs              # napi-build
  index.d.ts            # TypeScript type declarations
  package.json          # npm package metadata
  __test__/
    index.spec.mjs      # Node.js integration tests
```

```toml
# Cargo.toml
[package]
name = "ruvector-graph-transformer-node"
version = "2.0.4"
edition = "2021"
rust-version = "1.77"
license = "MIT"
description = "Node.js bindings for ruvector-graph-transformer via NAPI-RS"

[lib]
crate-type = ["cdylib"]

[dependencies]
ruvector-graph-transformer = { version = "2.0.4", path = "../ruvector-graph-transformer",
    features = ["full"] }
napi = { workspace = true }
napi-derive = { workspace = true }
serde_json = { workspace = true }

[build-dependencies]
napi-build = "2"

[profile.release]
lto = true
strip = true
```

### Node.js Binding Implementation (Training Example)

```rust
// src/training.rs
use napi::bindgen_prelude::*;
use napi_derive::napi;
use ruvector_graph_transformer::verified_training::{
    VerifiedTrainer, VerifiedTrainerConfig, TrainingCertificate,
};

#[napi(object)]
pub struct JsTrainingCertificate {
    pub total_steps: u32,
    pub violations: u32,
    pub final_loss: f64,
    pub final_coherence: Option<f64>,
    pub attestation_hex: String,
}

#[napi]
pub struct NodeVerifiedTrainer {
    inner: VerifiedTrainer,
}

#[napi]
impl NodeVerifiedTrainer {
    #[napi(constructor)]
    pub fn new(config_json: String) -> Result<Self> {
        let config: VerifiedTrainerConfig = serde_json::from_str(&config_json)
            .map_err(|e| Error::from_reason(e.to_string()))?;
        let inner = VerifiedTrainer::new(config)
            .map_err(|e| Error::from_reason(e.to_string()))?;
        Ok(Self { inner })
    }

    #[napi]
    pub fn step(&mut self, loss: f64, gradients_json: String) -> Result<String> {
        // Deserialize gradients, run step, serialize attestation
        // ...
    }

    #[napi]
    pub fn seal(&mut self) -> Result<JsTrainingCertificate> {
        // Seal training run and return certificate
        // ...
    }
}
```

### WASM Size Budget

Target: < 300 KB for the release `.wasm` binary (gzipped).

Size breakdown estimate:
| Component | Estimated Size |
|-----------|---------------|
| `ruvector-verified` (proof gates, arena, attestations) | ~40 KB |
| `ruvector-solver` (forward-push, random-walk, neumann) | ~60 KB |
| `ruvector-attention` (core attention only, no training) | ~80 KB |
| `ruvector-coherence` (metrics, no spectral) | ~15 KB |
| `wasm-bindgen` glue | ~20 KB |
| Serde JSON | ~50 KB |
| **Total (estimated)** | ~265 KB |

Size is controlled by:
1. `opt-level = "z"` (optimize for size)
2. `lto = true` (dead code elimination across crates)
3. `panic = "abort"` (no unwinding machinery)
4. `default-features = false` on `ruvector-graph-transformer` (only `proof-gated` and `sublinear-attention`)
5. Excluding training and the `spectral` feature from `ruvector-coherence`

If the target is exceeded, further reductions:
- Replace `serde_json` with `miniserde` (-30 KB)
- Strip `tracing` instrumentation via feature flag (-10 KB)
- Use `wasm-opt -Oz` post-processing (-10-20%)

### TypeScript Types

Both packages ship TypeScript type declarations. The WASM package generates types via `wasm-bindgen`'s `--typescript` flag. The Node.js package uses `napi-rs`'s automatic `.d.ts` generation from `#[napi]` attributes.

Key TypeScript interfaces:

```typescript
// Generated by wasm-bindgen / napi-rs

export interface GraphTransformerConfig {
  proofGated: boolean;
  attentionMechanism: 'ppr' | 'lsh' | 'spectral-sparsify';
  pprAlpha?: number;
  pprTopK?: number;
  lshTables?: number;
  lshBits?: number;
  spectralEpsilon?: number;
}

export interface ProofGatedOutput<T> {
  value: T;
  satisfied: boolean;
  attestationHex: string;
}

export interface ComplexityBound {
  opsUpperBound: number;
  memoryUpperBound: number;
  complexityClass: string;
}

export interface TrainingCertificate {
  totalSteps: number;
  violations: number;
  finalLoss: number;
  finalCoherence: number | null;
  attestationHex: string;
  invariantStats: InvariantStats[];
}
```

### Feature Parity Matrix

| Feature | Rust | WASM | Node.js |
|---------|------|------|---------|
| ProofGate<T> | Yes | Yes | Yes |
| Three-tier routing | Yes | Yes | Yes |
| Attestation chain | Yes | Yes | Yes |
| PPR-sampled attention | Yes | Yes | Yes |
| LSH spectral attention | Yes | Yes | Yes |
| Spectral sparsification | Yes | Yes | Yes |
| Hierarchical coarsening | Yes | No (1) | Yes |
| Memory-mapped processing | Yes | No (2) | Yes |
| VerifiedTrainer | Yes | No (3) | Yes |
| Robustness certification | Yes | No (3) | Yes |
| EWC continual learning | Yes | No (3) | Yes |
| Coherence (spectral) | Yes | No (4) | Yes |
| Coherence (basic) | Yes | Yes | Yes |

Notes:
1. Hierarchical coarsening uses `rayon` parallelism, unavailable in WASM
2. `mmap` is not available in WASM environments
3. Training is server-side only (see rationale above)
4. Spectral coherence uses `ndarray` with heavy numerics; excluded for size

### Build Pipeline

**WASM**:
```bash
cd crates/ruvector-graph-transformer-wasm
wasm-pack build --target web --release --out-dir ../../pkg/graph-transformer-wasm
# Verify size
ls -la ../../pkg/graph-transformer-wasm/*.wasm
```

**Node.js**:
```bash
cd crates/ruvector-graph-transformer-node
# NAPI-RS build for current platform
npx napi build --release --platform
# Cross-compile for CI (linux-x64-gnu, darwin-arm64, win32-x64-msvc)
npx napi build --release --target x86_64-unknown-linux-gnu
npx napi build --release --target aarch64-apple-darwin
npx napi build --release --target x86_64-pc-windows-msvc
```

### Testing Strategy

**WASM** (`wasm-bindgen-test`):
```rust
#[cfg(test)]
mod tests {
    use wasm_bindgen_test::*;
    wasm_bindgen_test_configure!(run_in_browser);

    #[wasm_bindgen_test]
    fn test_graph_transformer_roundtrip() {
        let config = r#"{"proofGated": true, "attentionMechanism": "ppr"}"#;
        let gt = WasmGraphTransformer::new(config).unwrap();
        assert!(gt.coherence().is_ok());
    }

    #[wasm_bindgen_test]
    fn test_proof_chain_returns_uint8arrays() {
        // Verify attestation chain serialization
    }
}
```

**Node.js** (via `jest` or `vitest`):
```javascript
import { GraphTransformer, VerifiedTrainer } from '@ruvector/graph-transformer-node';

test('forward pass returns proof-gated output', () => {
  const gt = new GraphTransformer('{"proofGated": true, "attentionMechanism": "ppr"}');
  const result = gt.forward(batchJson);
  expect(result.satisfied).toBe(true);
  expect(result.attestationHex).toHaveLength(164); // 82 bytes = 164 hex chars
});

test('verified training produces certificate', () => {
  const trainer = new VerifiedTrainer(configJson);
  for (let i = 0; i < 10; i++) {
    trainer.step(loss, gradientsJson);
  }
  const cert = trainer.seal();
  expect(cert.totalSteps).toBe(10);
  expect(cert.violations).toBe(0);
});
```

### npm Package Names

- WASM: `@ruvector/graph-transformer-wasm`
- Node.js: `@ruvector/graph-transformer-node`

Both published under the `ruvnet` npm account (already authenticated per `CLAUDE.md`).

## Consequences

### Positive

- TypeScript/JavaScript developers get proof-gated graph transformers with zero Rust toolchain requirement
- WASM < 300 KB enables browser-side inference with proof verification
- Node.js bindings get full feature parity including verified training
- Consistent binding patterns with existing `-wasm` and `-node` crates reduce maintenance burden
- TypeScript types provide compile-time safety for JS consumers

### Negative

- WASM lacks training, hierarchical coarsening, and spectral coherence -- feature gap may confuse users
- Two binding crates double the CI build matrix
- NAPI-RS cross-compilation requires platform-specific CI runners (or cross-rs)
- Serialization overhead (JSON for config, `Uint8Array` for attestations) adds latency compared to native Rust

### Risks

- WASM size may exceed 300 KB if `ruvector-solver` brings in unexpected transitive dependencies. Mitigated by `default-features = false` and `wasm-pack --release` size verification in CI
- NAPI-RS version 2.16 may introduce breaking changes in minor releases. Mitigated by pinning to workspace version
- Browser `WebAssembly.Memory` limits (4 GB on 64-bit, 2 GB on 32-bit) may be hit for large graphs. Mitigated by streaming processing and the `certify_complexity` API that rejects oversized graphs before execution

## Implementation

1. Create `crates/ruvector-graph-transformer-wasm/` following the structure above
2. Create `crates/ruvector-graph-transformer-node/` following the structure above
3. Add both to `[workspace.members]` in root `Cargo.toml`
4. Implement Tier 1 (core) bindings first, test with `wasm-bindgen-test` and Node.js
5. Implement Tier 2 (attention) bindings
6. Implement Tier 3 (training) in Node.js only
7. CI: add `wasm-pack build` and `napi build` to GitHub Actions workflow
8. Publish to npm: `@ruvector/graph-transformer-wasm` and `@ruvector/graph-transformer-node`

## References

- ADR-046: Graph Transformer Unified Architecture (module structure, feature flags)
- ADR-047: Proof-Gated Mutation Protocol (`ProofGate<T>`, `ProofAttestation` serialization)
- ADR-048: Sublinear Graph Attention (attention API surface)
- ADR-049: Verified Training Pipeline (`VerifiedTrainer`, `TrainingCertificate`)
- `crates/ruvector-gnn-wasm/Cargo.toml`: WASM binding pattern (opt-level "z", panic "abort")
- `crates/ruvector-gnn-node/Cargo.toml`: NAPI-RS binding pattern (napi-build, cdylib)
- `crates/ruvector-verified-wasm/Cargo.toml`: Verified WASM binding pattern (serde-wasm-bindgen)
- `crates/ruvector-graph-wasm/Cargo.toml`: Graph WASM binding pattern
- Workspace `Cargo.toml`: `wasm-bindgen = "0.2"`, `napi = { version = "2.16" }`, `napi-derive = "2.16"`