dearsky/wifi-densepose
1
0
Fork 0
Code Issues 20 Pull Requests 5 Actions Packages Projects Releases 1 Wiki Activity
Files
main
wifi-densepose/vendor/ruvector/docs/research/wasm-integration-2026/05-cross-stack-integration.md

23 KiB
Raw Permalink Blame History

Cross-Stack Integration Strategy: Unified Roadmap and Dependency Mapping

Document ID: wasm-integration-2026/05-cross-stack-integration Date: 2026-02-22 Status: Research Complete Classification: Engineering Strategy — Integration Architecture Series: Executive Summary | 01 | 02 | 03 | 04 | 05

Abstract

This document synthesizes the four preceding research documents into a unified integration roadmap for RuVector's WASM-compiled cognitive stack. It maps all inter-crate dependencies, identifies critical path items, proposes Architecture Decision Records (ADRs), and provides a phased execution timeline with concrete milestones. The goal is to move from the current state (independent WASM crates) to the target state (sealed cognitive container with canonical witness chains) in 16 weeks.

1. Current State Assessment

1.1 Crate Inventory

RuVector's workspace contains 85+ crates. The following are directly relevant to the WASM cognitive stack:

Crate Version WASM no_std Key Primitive
ruvector-core 2.0.3 No No VectorDB, HNSW index
ruvector-graph 0.1.x Via -wasm No Graph representation
ruvector-mincut 0.1.x Via -wasm No Dynamic min-cut (exact + approx)
ruvector-mincut-wasm 0.1.x Yes No WASM bindings for min-cut
ruvector-attn-mincut 0.1.x No No Attention-gated min-cut
ruvector-solver 0.1.x Via -wasm No 7 iterative solvers
ruvector-solver-wasm 0.1.x Yes No WASM solver bindings
ruvector-solver-node 0.1.x No (NAPI) No Node.js solver bindings
ruvector-gnn 0.1.x Via -wasm No GNN layers, training, EWC
ruvector-gnn-wasm 0.1.x Yes No WASM GNN bindings
ruvector-gnn-node 0.1.x No (NAPI) No Node.js GNN bindings
ruvector-coherence 0.1.x No No Coherence metrics
ruvector-sparse-inference 0.1.x Via -wasm No Sparse model inference
ruvector-sparse-inference-wasm 0.1.x Yes No WASM inference bindings
ruvector-wasm 0.1.x Yes No Unified WASM + kernel-pack
ruvector-math 0.1.x No Partial Math primitives
cognitum-gate-kernel 0.1.x Yes Yes no_std tile kernel
cognitum-gate-tilezero 0.1.x No No Tile arbiter / aggregator
prime-radiant 0.1.x No No Attention mechanisms

1.2 Dependency Graph (Current)

ruvector-core
├── ruvector-graph
│   ├── ruvector-graph-wasm
│   └── ruvector-mincut
│       ├── ruvector-mincut-wasm
│       ├── ruvector-attn-mincut
│       └── cognitum-gate-kernel  ←── no_std WASM tile
│           └── cognitum-gate-tilezero
├── ruvector-gnn
│   ├── ruvector-gnn-wasm
│   └── ruvector-gnn-node
├── ruvector-solver
│   ├── ruvector-solver-wasm
│   └── ruvector-solver-node
├── ruvector-coherence
├── ruvector-sparse-inference
│   └── ruvector-sparse-inference-wasm
├── prime-radiant
├── ruvector-math
└── ruvector-wasm  ←── unified WASM bindings + kernel-pack

1.3 Gap Analysis

Capability Current State Target State Gap
Min-cut output Randomized (non-canonical) Pseudo-deterministic (canonical) Cactus graph + lex tie-breaking
Spectral coherence Not implemented O(log n) SCS via solver engines New module in ruvector-coherence
Cold-tier GNN mmap infrastructure exists Hyperbatch training pipeline New cold-tier module
Cognitive container Components exist independently Sealed WASM container with witness New composition crate
Witness chain Per-tile fragments (non-canonical) Hash-chained Ed25519 receipts New witness layer
Epoch metering Exists in kernel-pack Extended to cognitive container Integration work

2. Dependency Mapping

2.1 New Feature Flags

Crate New Feature Depends On Purpose
ruvector-mincut canonical None Cactus graph, canonical tie-breaking
ruvector-coherence spectral ruvector-solver Spectral coherence scoring
ruvector-gnn cold-tier mmap Hyperbatch training pipeline
cognitum-gate-kernel canonical-witness ruvector-mincut/canonical Canonical witness fragments

2.2 New Crates

Crate Dependencies Purpose
ruvector-cognitive-container cognitum-gate-kernel, ruvector-solver-wasm, ruvector-mincut-wasm, ruvector-wasm/kernel-pack Sealed cognitive container
ruvector-cognitive-container-wasm ruvector-cognitive-container WASM bindings for container

2.3 Target Dependency Graph

ruvector-core
├── ruvector-graph
│   └── ruvector-mincut
│       ├── [NEW] canonical feature (cactus + lex tie-break)
│       ├── ruvector-mincut-wasm
│       ├── ruvector-attn-mincut
│       └── cognitum-gate-kernel
│           ├── [NEW] canonical-witness feature
│           └── cognitum-gate-tilezero
├── ruvector-gnn
│   ├── [NEW] cold-tier feature (hyperbatch + hotset)
│   ├── ruvector-gnn-wasm
│   └── ruvector-gnn-node
├── ruvector-solver
│   ├── ruvector-solver-wasm
│   └── ruvector-solver-node
├── ruvector-coherence
│   └── [NEW] spectral feature (SCS via solver)
├── ruvector-wasm (kernel-pack)
│
└── [NEW] ruvector-cognitive-container
    ├── cognitum-gate-kernel (canonical-witness)
    ├── ruvector-solver-wasm (spectral scoring)
    ├── ruvector-mincut-wasm (canonical min-cut)
    └── ruvector-wasm/kernel-pack (epoch + signing)
        └── [NEW] ruvector-cognitive-container-wasm

3. Critical Path Analysis

3.1 Dependency Order

The integration must proceed in dependency order:

Phase 1 (Foundations):
  ruvector-mincut/canonical  ───→  No dependencies
  ruvector-coherence/spectral ──→  ruvector-solver (exists)
  ruvector-gnn/cold-tier ───────→  ruvector-gnn/mmap (exists)

Phase 2 (Integration):
  cognitum-gate-kernel/canonical-witness ──→  ruvector-mincut/canonical

Phase 3 (Composition):
  ruvector-cognitive-container ──→  All Phase 1-2 outputs

Phase 4 (WASM Packaging):
  ruvector-cognitive-container-wasm ──→  Phase 3 output

3.2 Critical Path

The longest dependency chain determines the minimum timeline:

ruvector-mincut/canonical (4 weeks)
    → cognitum-gate-kernel/canonical-witness (2 weeks)
        → ruvector-cognitive-container (4 weeks)
            → ruvector-cognitive-container-wasm (2 weeks)
                = 12 weeks critical path

With 4 weeks of buffer and parallel work on spectral/cold-tier: 16 weeks total.

3.3 Parallel Work Streams

Stream Weeks 0-4 Weeks 4-8 Weeks 8-12 Weeks 12-16
A: Min-Cut Cactus data structure + builder Canonical selection + dynamic Wire to gate-kernel Container integration
B: Spectral Fiedler estimator via CG SCS tracker + incremental WASM benchmark Container integration
C: GNN Cold-Tier Feature storage + hyperbatch iter Hotset + direct I/O EWC cold-tier WASM model export
D: Container Memory slab + arena design Witness chain + signing Tick execution + epoch WASM packaging + test

Streams A-C are independent in Phase 1, enabling full parallelism.

4. Proposed Architecture Decision Records

4.1 ADR-011: Canonical Min-Cut Feature

Status: Proposed Context: The current ruvector-mincut produces non-deterministic cut outputs. Decision: Add a canonical feature flag implementing pseudo-deterministic min-cut via cactus representation and lexicographic tie-breaking. Consequences:

  • ~1.8x overhead for canonical mode vs. randomized
  • Enables reproducible witness fragments in cognitum-gate-kernel
  • Cactus representation adds ~4KB per tile (within 64KB budget)

4.2 ADR-012: Spectral Coherence Scoring

Status: Proposed Context: No real-time structural health metric exists for HNSW graphs. Decision: Add a spectral feature to ruvector-coherence that computes a composite Spectral Coherence Score (SCS) using existing ruvector-solver engines. Consequences:

  • New dependency: ruvector-coherence → ruvector-solver
  • O(log n) amortized SCS updates via perturbation theory
  • Enables proactive index health monitoring

4.3 ADR-013: Cold-Tier GNN Training

Status: Proposed Context: ruvector-gnn cannot train on graphs exceeding available RAM. Decision: Add a cold-tier feature (depending on mmap) implementing hyperbatch training with block-aligned I/O, hotset caching, and double-buffered prefetch. Consequences:

  • 3-4x throughput improvement over naive disk-based training
  • Not available on WASM targets (mmap not supported)
  • Server-to-WASM model export path for deployment

4.4 ADR-014: Cognitive Container Standard

Status: Proposed Context: RuVector's WASM-compiled cognitive primitives exist independently without a unified execution model. Decision: Create ruvector-cognitive-container crate that composes gate-kernel + solver + mincut into a sealed WASM container with fixed memory slab, epoch budgeting, and Ed25519 witness chains. Consequences:

  • New crate (not a modification of existing crates)
  • 4 MB default memory slab, 64 WASM pages
  • ~189 μs per tick in WASM (~5,300 ticks/second)
  • Enables regulatory compliance for auditable AI systems

5. Integration Test Strategy

5.1 Unit Tests (Per Feature)

Feature Test Category Key Properties
canonical min-cut Determinism Same graph → same canonical cut across 1000 runs
canonical min-cut Correctness Canonical cut value = true min-cut value
canonical min-cut Dynamic Insert/delete sequence → canonical cut matches static recomputation
spectral SCS Monotonicity Removing edges decreases SCS for connected graphs
spectral SCS Bounds 0 ≤ SCS ≤ 1 for all valid graphs
spectral SCS Incremental accuracy Incremental SCS within 5% of full recomputation
cold-tier training Convergence Cold-tier loss curve within 2% of in-memory baseline
cold-tier training Correctness Gradient accumulation matches in-memory computation
Container Determinism Same deltas → same witness receipt across runs
Container Chain integrity verify_witness_chain succeeds for valid chains
Container Epoch budgeting Tick completes within allocated budget

5.2 Integration Tests (Cross-Crate)

Test Crates Involved Description
Canonical gate coherence mincut + gate-kernel Canonical witness fragments aggregate correctly
Spectral + behavioral coherence + solver SCS correlates with behavioral coherence metrics
Container end-to-end All container crates Full tick cycle produces valid witness receipt
WASM determinism container-wasm Same input deltas → identical WASM output across runtimes
Multi-tile aggregation container + tilezero 256 containers produce reproducible global decision

5.3 Performance Benchmarks

Benchmark Target Measurement
Canonical min-cut overhead < 2x vs. randomized Criterion.rs microbenchmark
SCS full recompute (10K vertices) < 15 ms Criterion.rs
SCS incremental update < 100 μs Criterion.rs
Container tick (WASM) < 200 μs wasm-bench
Container tick (native) < 100 μs Criterion.rs
Cold-tier throughput (10M nodes, NVMe) > 3x naive disk Custom benchmark
Ed25519 sign (WASM) < 100 μs wasm-bench

6. Risk Assessment

6.1 Technical Risks

Risk Probability Impact Mitigation
Cactus construction too slow for WASM tiles Medium High Pre-compute cactus on delta ingestion, not per-tick
Floating-point non-determinism in spectral scoring Medium High Use fixed-point arithmetic (FixedWeight type)
Cold-tier I/O latency exceeds compute time Low Medium Triple-buffering, larger hyperbatches
WASM memory growth needed beyond initial slab Low High Conservative slab sizing, fail-fast on OOM
Ed25519 signing too slow for real-time ticks Low Medium Deferred batch signing option

6.2 Organizational Risks

Risk Probability Impact Mitigation
Parallel streams create merge conflicts Medium Medium Clear crate boundaries, feature flags
Scope creep in container design High Medium ADR-014 locks scope; feature flags for extensions
Testing infrastructure insufficient Low High Invest in WASM test harness early (Week 1)

7. Publishing Strategy

7.1 Crate Publication Order

Following the existing publish order rule (ruvector-solver first, then -wasm and -node):

Phase 1 Publications (after Week 4):
  1. ruvector-mincut (with canonical feature)
  2. ruvector-mincut-wasm (updated)
  3. ruvector-solver (unchanged, but verify compatibility)
  4. ruvector-solver-wasm (unchanged)

Phase 2 Publications (after Week 8):
  5. ruvector-coherence (with spectral feature)
  6. cognitum-gate-kernel (with canonical-witness feature)
  7. ruvector-gnn (with cold-tier feature)
  8. ruvector-gnn-wasm (updated)

Phase 3 Publications (after Week 16):
  9. ruvector-cognitive-container (new)
  10. ruvector-cognitive-container-wasm (new)

7.2 Pre-Publication Checklist

For each crate publication:

  • cargo publish --dry-run --allow-dirty passes
  • All tests pass: cargo test --all-features
  • WASM compilation succeeds: wasm-pack build --target web
  • No new security advisories: cargo audit
  • Documentation builds: cargo doc --no-deps
  • Version bump follows semver (feature additions = minor bump)
  • CHANGELOG.md updated
  • npm publish for -wasm and -node variants (npm whoami = ruvnet)

7.3 Version Strategy

Crate Current After Phase 1 After Phase 2 After Phase 3
ruvector-mincut 0.1.x 0.2.0 0.2.x 0.2.x
ruvector-coherence 0.1.x 0.1.x 0.2.0 0.2.x
ruvector-gnn 0.1.x 0.1.x 0.2.0 0.2.x
cognitum-gate-kernel 0.1.x 0.1.x 0.2.0 0.2.x
ruvector-cognitive-container — — — 0.1.0

8. Milestone Schedule

8.1 Phase 1: Foundations (Weeks 0-4)

Week 1:

  • Create canonical feature flag in ruvector-mincut/Cargo.toml
  • Implement CactusGraph, CactusVertex, CactusEdge data structures
  • Create spectral feature flag in ruvector-coherence/Cargo.toml
  • Implement estimate_fiedler() using existing CgSolver
  • Set up WASM test harness for container integration testing

Week 2:

  • Implement static cactus builder via tree packing algorithm
  • Implement SpectralCoherenceScore struct with four-component formula
  • Create cold-tier feature flag in ruvector-gnn/Cargo.toml
  • Implement FeatureStorage for block-aligned feature file layout

Week 3:

  • Implement canonical lex tie-breaking on rooted cactus
  • Implement SpectralTracker with perturbation-based incremental updates
  • Implement HyperbatchIterator with double-buffered prefetch
  • Write property-based tests for canonical min-cut determinism

Week 4:

  • Implement FixedWeight type for deterministic comparison
  • Benchmark SCS computation in ruvector-solver-wasm
  • Implement BFS vertex reordering for cold-tier
  • Milestone: All three feature flags working with unit tests passing

8.2 Phase 2: Integration (Weeks 4-8)

Week 5:

  • Implement dynamic cactus maintenance (incremental updates)
  • Wire SCS into ruvector-coherence evaluate_batch pipeline
  • Implement AdaptiveHotset with greedy selection and decay

Week 6:

  • Wire canonical witness fragment into cognitum-gate-kernel
  • Add spectral health monitoring to HNSW graph
  • Add direct I/O support on Linux (O_DIRECT) for cold-tier

Week 7:

  • Implement ColdTierEwc for disk-backed Fisher information
  • Compile and test canonical min-cut in ruvector-mincut-wasm
  • Benchmark canonical overhead vs. randomized min-cut

Week 8:

  • Integration tests: canonical gate coherence, spectral + behavioral
  • Benchmark cold-tier on ogbn-products dataset
  • Milestone: All integration tests passing, Phase 1-2 crates publishable

8.3 Phase 3: Composition (Weeks 8-12)

Week 9:

  • Create ruvector-cognitive-container crate skeleton
  • Implement MemorySlab with fixed-size arena allocation
  • Define ContainerWitnessReceipt struct and serialization

Week 10:

  • Implement hash chain (SHA256) and Ed25519 signing
  • Wire cognitum-gate-kernel as first container component
  • Implement epoch-budgeted tick execution

Week 11:

  • Integrate ruvector-solver-wasm spectral scoring
  • Integrate ruvector-mincut-wasm canonical min-cut
  • Implement witness chain verification API

Week 12:

  • End-to-end container tests (determinism, chain integrity)
  • Performance benchmarks (tick latency, memory usage)
  • Milestone: Cognitive container working in native mode

8.4 Phase 4: WASM Packaging (Weeks 12-16)

Week 13:

  • Build WASM compilation pipeline (wasm-pack)
  • Test container in browser via wasm-bindgen
  • Implement container snapshotting and restoration

Week 14:

  • Multi-container orchestration for 256-tile fabric
  • Cross-runtime determinism testing (Wasmtime, Wasmer, browser)
  • WasmModelExport for server-to-WASM GNN model transfer

Week 15:

  • Final performance optimization pass
  • Security audit of witness chain and signing
  • Documentation and API reference generation

Week 16:

  • Publish all Phase 1-3 crates to crates.io
  • Publish WASM packages to npm
  • Milestone: Full cognitive container stack published and deployable

9. Success Criteria

9.1 Quantitative Targets

Metric Target Measurement
Canonical min-cut determinism 100% across 10,000 runs Property test
SCS computation (10K vertices, WASM) < 30 ms Benchmark
Container tick (WASM) < 200 μs Benchmark
Container ticks/second (WASM) > 5,000 Benchmark
Cold-tier throughput improvement > 3x vs. naive Benchmark on ogbn-products
Witness chain verification < 1 ms per receipt Benchmark
WASM binary size (container) < 2 MB wasm-opt -Os
Memory usage (standard config) 4 MB fixed Runtime measurement

9.2 Qualitative Targets

  • All new features behind feature flags (no breaking changes to existing API)
  • All crates maintain existing test coverage + new tests
  • WASM binaries pass the same test suite as native
  • Documentation for all public APIs
  • ADRs approved and merged

10. Vertical Deployment Roadmap

10.1 Immediate Applications (Post-Phase 4)

Vertical Product Cognitive Container Role
Finance Fraud detection dashboard Browser WASM: real-time transaction graph monitoring with auditable witness chain
Cybersecurity SOC network monitor Browser WASM: spectral coherence for network fragility detection
Healthcare Diagnostic AI audit Server WASM: deterministic decision replay for FDA SaMD compliance
Edge/IoT Anomaly detector 256KB WASM: minimal cognitive container on ARM microcontrollers

10.2 SDK and API Surface

// @ruvector/cognitive-container (npm package)

// Browser usage
import { CognitiveContainer, verify_chain } from '@ruvector/cognitive-container';

const container = await CognitiveContainer.create({
    profile: 'browser',  // 1MB slab, 5K epoch budget
});

// Feed data, get auditable decisions
const receipt = container.tick([
    { type: 'edge_add', u: 0, v: 1, weight: 1.0 },
    { type: 'observation', node: 0, value: 0.95 },
]);

// Verify audit trail
const chain = container.get_receipt_chain();
const valid = verify_chain(chain, container.public_key());

// Rust server usage
use ruvector_cognitive_container::prelude::*;

let container = ContainerBuilder::new()
    .profile(Profile::Standard)  // 4MB slab, 10K epoch budget
    .build()?;

let receipt = container.tick(&deltas)?;
assert_eq!(receipt.decision, CoherenceDecision::Pass);

// Verify chain
let chain = container.receipt_chain();
assert!(verify_witness_chain(&chain, container.public_key()).is_valid());

11. Open Questions (Cross-Cutting)

  1. Feature flag combinatorics: With 4 new features across 4 crates, how do we ensure all valid combinations compile and test correctly? (Consider feature-flag CI matrix.)

  2. WASM Component Model: Should the cognitive container adopt the WASM Component Model (WIT interfaces) for inter-component communication instead of shared linear memory? Trade-off: isolation vs. performance.

  3. Backwards compatibility: The canonical feature in ruvector-mincut adds new types. Should the existing DynamicMinCut trait be extended or should CanonicalMinCut be a separate trait? (Separate trait recommended to avoid breaking changes.)

  4. Monitoring integration: Should the cognitive container expose Prometheus-compatible metrics via WASM imports? Or should monitoring be handled entirely by the host?

  5. Multi-language bindings: Beyond Rust, WASM, and Node.js — should we generate Python bindings (via PyO3) for the cognitive container? (Deferred to post-Phase 4.)

12. Summary

The RuVector WASM cognitive stack integration is a 16-week effort that:

  1. Adds canonical min-cut to ruvector-mincut via cactus representation (Doc 01)
  2. Adds spectral coherence scoring to ruvector-coherence via existing solvers (Doc 02)
  3. Adds cold-tier GNN training to ruvector-gnn via hyperbatch I/O (Doc 03)
  4. Creates a sealed WASM cognitive container composing all primitives with witness chains (Doc 04)
  5. Follows a phased roadmap with clear milestones and dependency ordering (this document)

The integration is designed to be non-breaking (all new features behind feature flags), publishable (following existing crates.io/npm publishing conventions), and deployable (browser, server, edge, and IoT configurations).

The end result is a verifiable, auditable, deterministic cognitive computation unit — deployable as a single WASM binary — that produces tamper-evident witness chains suitable for regulated AI environments.

References

  1. Documents 01-04 in this series
  2. RuVector Workspace Cargo.toml (85+ crate definitions)
  3. ADR-005: Kernel Pack System (existing)
  4. EU AI Act, Article 13: Transparency Requirements
  5. FDA SaMD Guidance: Software as a Medical Device
  6. WebAssembly Component Model Specification (W3C Draft)
  7. Semantic Versioning 2.0.0 (semver.org)

Document Navigation

Reference in New Issue View Git Blame Copy Permalink