Rivox

Universal Polyglot Build Coordination Layer

Coordinate. Never Replace.

crates.io • docs.rs • GitHub • Overview • Installation • Quick Start • Architecture • CLI Reference

---

Table of Contents

• Overview
• Why Rivox
• The Architectural Constitution
• Installation
• Quick Start
• Architecture
• Supported Ecosystems
• Core Features
• CLI Reference
• Subtree Content-Addressed Storage (CAS)
• Process Sandboxing
• Supply-Chain Provenance & SBOM
• OCI Target Exporter
• Deterministic Policy Engine
• Reproducibility Model
• Security Model
• Honest Limitations
• Frequently Asked Questions (FAQ)
• CI/CD Integration
• Documentation Index
• Development & Testing
• Roadmap
• License

---

Overview

Rivox is a universal build-coordination, caching, and provenance layer designed for polyglot monorepos containing Python, Rust, Node.js, Go, and Java/Gradle services.

Instead of forcing developers to rewrite external dependencies into complex Bazel Starlark or Nix derivations, Rivox wraps native ecosystem resolvers (uv, cargo, pnpm, go, gradle) to construct a unified multigraph, execute sandboxed builds, derive Merkle subtree cache keys, and emit signed supply-chain attestations.

---

Why Rivox

Engineering organizations running polyglot monorepos face three recurring pain points:

• Redundant CI Builds: Each ecosystem's dependency resolution and build steps run independently without shared caching awareness.
• Cache Invalidation Cascades: A change in a single Python package invalidates unrelated Rust or Node compilation steps in CI.
• Fragmented Supply-Chain Security: Security teams must query pip, npm, crates.io, Go, and Maven trees separately to track CVEs.

Rivox addresses these challenges by coordinating native tools and providing zero-copy content-addressed caching across all ecosystems without replacing native dependency resolvers.

---

The Architectural Constitution

1. Coordinate. Never Replace. Rivox delegates 100% of dependency resolution authority to native ecosystem tools.
2. Native lockfiles (uv.lock, Cargo.lock, pnpm-lock.yaml, go.sum, gradle.lockfile) remain authoritative.
3. Every build operation is 100% deterministic and reproducible.
4. AI never participates in build or resolution decisions.

---

Installation

Install via Cargo (Recommended)

Rivox is published on crates.io:

cargo install rivox

Verify the installation:

rivox --version
rivox --help

Build from Source

git clone https://github.com/Grevix/Rivox.git
cd Rivox
cargo build --release
sudo cp target/release/rivox /usr/local/bin/

---

Quick Start

1. Initialize rivox.toml

Create rivox.toml at the root of your polyglot monorepo:

[project]
name = "my-polyglot-monorepo"
version = "1.0.0"

[ecosystems.python]
path = "services/api"
tool = "uv"

[ecosystems.rust]
path = "services/core"
tool = "cargo"

[ecosystems.node]
path = "services/web"
tool = "pnpm"

[[cross_refs]]
consumer = "python:services/api"
dependency = "rust:services/core"
type = "native_extension"

2. Run Coordinated Build

rivox build

3. Verify Lockfile & Parity

rivox verify

---

Architecture

flowchart LR
    subgraph Resolvers [Native Resolvers]
        Py[Python / uv]
        Rs[Rust / cargo]
        Js[Node.js / pnpm]
        Go[Go / go]
        Jv[Java / gradle]
    end

    subgraph Core [Rivox Core]
        UG[Unified Build Graph]
        WS[Async Wavefront Scheduler]
        SB[OS Sandbox Executor]
    end

    subgraph Storage [Storage & Security]
        CAS[Subtree CAS Cache]
        Prov[Sigstore / SLSA Provenance]
        Lock[rivox.lock]
    end

    Py --> UG
    Rs --> UG
    Js --> UG
    Go --> UG
    Jv --> UG

    UG --> WS
    WS --> SB
    SB --> CAS
    SB --> Prov
    CAS --> Lock
    Prov --> Lock

Loading

---

Supported Ecosystems

Ecosystem	Native Tool	Lockfile	Status
Python	uv	uv.lock	Operational
Rust	cargo	Cargo.lock	Operational
Node.js	pnpm	pnpm-lock.yaml	Operational
Go	go	go.sum / go.mod	Operational
Java	gradle	gradle.lockfile	Operational

---

Core Features

• Native Ecosystem Coordination: Integrates directly with native lockfiles and resolution engines.
• Unified Multigraph (petgraph::DiGraph): Merges ecosystem dependency subgraphs and explicit cross_refs.
• Subtree Merkle CAS Keys (RFC-001): Derives granular cache keys (derive_subtree_cache_key) to prevent global cache invalidation cascades.
• Async Wavefront Scheduler: Partitions independent graph nodes into parallel execution levels (plan_wavefronts).
• OS Sandboxing: Supports Linux namespaces (bwrap), macOS Seatbelt (sandbox-exec), and Windows job isolation.
• Supply-Chain Security: Emits in-toto link metadata, SLSA Level 2 claims, SPDX 2.3 JSON SBOMs, and Sigstore/Rekor hashedrekord schemas.
• REAPI v2 Remote Execution: Compatible with Remote Execution API (REAPI v2) storage servers and remote execution workers.
• OCI Image Container Layout: Exports build artifacts directly into deterministic OCI image layout tarballs (rivox oci build).
• Incremental Graph Diffing: Compares lockfile revisions (rivox graph diff) to calculate graph mutations and rebuild requirements.
• Deterministic Policy Engine: Machine-readable organization policy rules (.rivox/policy.toml).

---

CLI Reference

Command	Subcommand	Purpose	Example
rivox build	—	Coordinates lockfiles, builds DAG, and caches artifacts	rivox build --frozen
rivox cache	status | prune | export	Inspects, cleans, or exports CAS cache	rivox cache prune --days 30
rivox graph	diff	Computes incremental lockfile graph diffs	rivox graph diff old.lock new.lock
rivox oci	build	Exports build artifacts to deterministic OCI layout	rivox oci build --target app
rivox policy	check	Evaluates project graph against policy rules	rivox policy check
rivox remote	exec	Executes build action on REAPI v2 remote worker	rivox remote exec --action <digest>
rivox verify	—	Validates lockfile parity and provenance signatures	rivox verify
rivox benchmark	—	Executes internal Merkle key and CAS benchmarks	rivox benchmark
rivox completions	bash | zsh | fish	Generates shell completion scripts	rivox completions zsh

---

Subtree Content-Addressed Storage (CAS)

Rivox uses recursive Merkle cache key derivation (RFC-001). The cache key for a package node depends only on its own artifact content hash, platform triple, and transitive dependency subgraphs. A lockfile change in an unrelated Python package does not invalidate the subtree cache key of a Rust or Node service.

Local storage (~/.rivox/cache/cas) uses a 2-level fanout directory layout with zero-copy hard-linking and LRU Garbage Collection (rivox cache prune).

---

Process Sandboxing

Build execution commands run inside isolated OS environments:

• Linux: Unprivileged namespaces (CLONE_NEWNS, CLONE_NEWNET) via /usr/bin/bwrap.
• macOS: /usr/bin/sandbox-exec with generated Seatbelt policy profiles.
• Windows: Process isolation policies (windows-job-objects) and proxy environment scrubbing.

---

Supply-Chain Provenance & SBOM

Every rivox build emits:

• in-toto Metadata: Link metadata per build step recording inputs, outputs, commands, and sandbox environment.
• SLSA Level 2: Hosted CI build platform SLSA Level 2 provenance JSON statements.
• SPDX 2.3 SBOM: JSON SBOM detailing complete dependency closures.
• Sigstore / Rekor: hashedrekord v0.0.1 log entry JSON schemas and SET UUID references (rekor:...).

---

OCI Target Exporter

The rivox oci build command exports build artifacts directly into deterministic OCI image layout tarballs (oci-layout, index.json, manifest.json, config.json, and layer tarballs) normalized with SOURCE_DATE_EPOCH.

---

Deterministic Policy Engine

Machine-readable organization policy rules can be declared in .rivox/policy.toml:

[policy]
allowed_ecosystems = ["python", "rust", "node", "go", "gradle"]
blocked_packages = ["malicious-pkg"]
require_sandbox = true
max_artifact_size_mb = 500

Evaluate policy compliance via:

rivox policy check

---

Reproducibility Model

Rivox enforces determinism at every stage:

• Native lockfiles pin exact resolved package versions.
• Merkle subtree keys eliminate non-deterministic input timestamps and build paths.
• SOURCE_DATE_EPOCH normalizes timestamps in generated SBOMs and OCI tarballs.
• OS process sandboxing prevents ambient network/filesystem leaks during compilation.

---

Security Model

• No New Trust Roots: Package trust continues to derive directly from PyPI, crates.io, npm, Go proxies, and Maven repositories.
• Path Traversal Protection: All CAS restores, worker executions, and OCI exports enforce strict path validation (validate_path_security).
• Default-Deny Network Sandboxing: Build sandboxes default-deny network access unless explicitly allow-listed in rivox.toml.

---

Honest Limitations

• No AI in Resolution Path: AI never participates in dependency resolution, graph construction, or build decisions.
• SLSA Level 2: Rivox claims SLSA Level 2 (scripted build platform + platform-generated provenance); it does not claim SLSA Level 3 (full hermeticity) for arbitrary unmonitored native build scripts.
• Host Prerequisites: Native ecosystem tools (uv, cargo, pnpm, go, gradle) must be installed on the host build environment.

---

Frequently Asked Questions (FAQ)

Q: Does Rivox replace uv, cargo, or pnpm? A: No. Rivox delegates resolution authority to native tools and coordinates their outputs into a single multigraph and cache.

Q: Is Rivox published on crates.io? A: Yes! Rivox v1.0.0 is available on crates.io and can be installed via cargo install rivox.

Q: Does Rivox require a daemon or server? A: No. Rivox is a standalone CLI binary that operates entirely locally or connects to standard REAPI gRPC caches when configured.

Q: How does Rivox handle cross-ecosystem dependencies? A: Cross-ecosystem build-order dependencies (e.g., a Python wheel embedding a Rust native extension) are explicitly declared in rivox.toml under [[cross_refs]].

---

CI/CD Integration

Example GitHub Actions workflow (.github/workflows/ci.yml):

name: Polyglot CI Pipeline

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - name: Install Ecosystem Prerequisites
        run: |
          pip install uv
          npm install -g pnpm
      - name: Install Rivox
        run: cargo install --path .
      - name: Run Rivox Coordinated Build
        run: rivox build --frozen

---

Documentation Index

• System Architecture
• Design Principles
• Content-Addressed Storage (CAS)
• OS Sandbox Isolation
• Supply-Chain Security
• Configuration Reference
• CLI Manual
• Comparison to Nix/Bazel
• Release Gate Scorecard
• Final Release Audit Report

---

Development & Testing

# Check compilation across all targets and features
cargo check --workspace --all-targets --all-features

# Run formatting checks
cargo fmt --all -- --check

# Run linter
cargo clippy --workspace --all-targets --all-features -- -D warnings

# Execute full unit and integration test suite
cargo test --workspace --all-targets --all-features

---

Roadmap

Current — v1.0.0

• Python (uv), Rust (cargo), Node.js (pnpm), Go (go), Java/Gradle (gradle) adapters.
• Subtree Merkle CAS, OS Sandboxing, Sigstore/Rekor Provenance.
• REAPI Remote Execution & Workers, OCI Container Exporter, Graph Diffing, Deterministic Policy Engine.

Future Development

• Expanded ecosystem adapters (.NET, Ruby).
• Extended IDE integration plugins.
• Advanced remote execution worker fleet management.

---

License

Rivox is dual-licensed under MIT OR Apache-2.0.

Maintainer: Aaryan Rawat (aaryan28rwt@gmail.com)