wifi-densepose/vendor/ruvector/npm/packages/sona/BUILD_INSTRUCTIONS.md

SONA NAPI-RS Build Instructions

Overview

This document describes how to build the SONA Node.js native module from the Rust crate using NAPI-RS.

Prerequisites

• Rust toolchain (1.70+)
• Node.js (16+)
• npm or yarn
• @napi-rs/cli

Directory Structure

/workspaces/ruvector/
├── crates/sona/                  # Rust crate
│   ├── src/
│   │   ├── napi_simple.rs        # NAPI bindings
│   │   ├── engine.rs             # Core engine
│   │   ├── lora.rs               # LoRA implementations
│   │   ├── types.rs              # Type definitions
│   │   └── ...
│   ├── Cargo.toml                # Rust dependencies
│   └── build.rs                  # Build script
└── npm/packages/sona/            # NPM package
    ├── package.json              # NPM configuration
    ├── index.js                  # JavaScript entry point
    ├── index.d.ts                # TypeScript definitions
    ├── examples/                 # Example scripts
    └── test/                     # Test files

Build Steps

1. Build the Rust crate with NAPI feature

cd /workspaces/ruvector/crates/sona
cargo build --release --features napi

2. Build the Node.js module

cd /workspaces/ruvector/npm/packages/sona
npm install
npm run build

This will:

• Install dependencies including @napi-rs/cli
• Build the native module for your platform
• Generate platform-specific .node files

3. Run tests

npm test

4. Run examples

node examples/basic-usage.js
node examples/custom-config.js
node examples/llm-integration.js

NAPI-RS Configuration

The build is configured via package.json:

{
  "napi": {
    "name": "sona",
    "triples": {
      "defaults": true,
      "additional": [
        "x86_64-unknown-linux-musl",
        "aarch64-unknown-linux-gnu",
        "armv7-unknown-linux-gnueabihf",
        "aarch64-apple-darwin",
        "x86_64-pc-windows-msvc",
        "aarch64-pc-windows-msvc"
      ]
    }
  }
}

Cross-Compilation

To build for multiple platforms:

npm run build -- --target x86_64-unknown-linux-musl
npm run build -- --target aarch64-apple-darwin
npm run build -- --target x86_64-pc-windows-msvc

Publishing

Prepare for publishing

napi prepublish -t npm

Create universal binary (macOS)

napi universal

Publish to npm

npm publish

API Differences from Rust

The NAPI bindings use a simplified API compared to the Rust API:

Rust API (via begin_trajectory)

let builder = engine.begin_trajectory(embedding);
builder.add_step(activations, attention, reward);
engine.end_trajectory(builder, quality);

Node.js API (via trajectory ID)

const trajId = engine.beginTrajectory(embedding);
engine.addTrajectoryStep(trajId, activations, attention, reward);
engine.setTrajectoryRoute(trajId, "route");
engine.endTrajectory(trajId, quality);

This design avoids exposing the TrajectoryBuilder struct to JavaScript, which simplifies NAPI bindings.

Troubleshooting

Build fails with "could not find `napi`"

Ensure you're building with the napi feature:

cargo build --features napi

Module not found at runtime

The native module must be built before running Node.js code:

npm run build

Platform-specific issues

Check that your Rust toolchain supports the target platform:

rustup target list
rustup target add <target-triple>

Performance Notes

• The native module uses zero-copy for Float64Arrays where possible
• Global trajectory storage uses OnceLock for thread-safe initialization
• Mutex-protected HashMap for trajectory builders (minimal contention)

Memory Management

• Trajectory builders are stored globally until endTrajectory is called
• Finished trajectories are automatically cleaned up
• No manual memory management required in JavaScript

Feature Flags

The NAPI bindings respect these Cargo features:

• napi - Enable NAPI bindings (required)
• serde-support - Required by napi feature
• simd - Enable SIMD optimizations (optional, recommended)

Build with all features:

cargo build --release --features napi,simd

License

MIT OR Apache-2.0