Rivox

Universal Polyglot Build Coordination Layer

Coordinate. Never Replace.

Vision • Architecture • Installation • Quick Start • CLI Reference • Documentation

---

Vision & Core Philosophy

Rivox is NOT another package manager. Rivox is NOT an independent dependency resolver.

Modern engineering teams at 50–2,000-engineer scale operate polyglot monorepos containing Python, Node.js, and Rust services. Currently, these organizations maintain independent package managers (uv, cargo, pnpm), independent lockfiles, and bespoke CI caching scripts.

Bazel and Nix attempt to solve this by requiring engineers to rewrite external dependencies into custom Starlark or Nix derivations — introducing massive onboarding friction and maintenance debt.

Rivox introduces a new category: Universal Polyglot Build Coordination.

Python  -->  uv    --┐
Rust    -->  cargo --┼-->  [ Rivox Unified Multigraph ]  -->  [ Subtree CAS Cache ]  -->  [ Signed Provenance ]
Node.js -->  pnpm   --┘

The Architectural Constitution

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

---

Key Features

• Zero-Migration Polyglot Coordination: Native uv, cargo, and pnpm workspaces work out-of-the-box.
• Subtree-Based CAS Caching (RFC-001): Recursive Merkle cache key derivation prevents global lockfile changes from invalidating unrelated package caches.
• Merkleized Directory Storage (RFC-002): OS-compliant file blob deduplication and zero-copy hard-linking (~/.rivox/cache/cas).
• OS Process Sandboxing (RFC-004): Unprivileged Linux namespaces (CLONE_NEWNS, CLONE_NEWNET) and macOS Seatbelt sandbox profiles.
• Supply-Chain Security Out-of-the-Box: Emits signed in-toto, SLSA Level 2, SPDX 2.3 JSON (RFC-005), and Sigstore/Rekor attestations.
• REAPI Compatibility: Plug-and-play gRPC remote cache client for Buildbarn and bazel-remote.

---

Architecture Overview

+-------------------------------------------------------------------------------+
|                             rivox.toml Manifest                               |
+-------------------------------------------------------------------------------+
                                       │
                                       ▼
+-------------------------------------------------------------------------------+
|                            Rivox CLI Coordinator                              |
|       ┌───────────────────┬───────────────────┬───────────────────┐           |
|       │  Python Adapter   │   Rust Adapter    │   Node Adapter    │           |
|       │     (uv lock)     │ (cargo metadata)  │ (pnpm-lock.yaml)  │           |
|       └─────────┬─────────┴─────────┬─────────┴─────────┬─────────┘           |
+─────────────────┼───────────────────┼───────────────────┼────────────────-----+
                  │                   │                   │
                  └───────────────────┼───────────────────┘
                                      │
                                      ▼
+-------------------------------------------------------------------------------+
|                           Unified Multigraph Builder                          |
|                     (petgraph DAG + Cross-Ecosystem Edges)                    |
+-------------------------------------------------------------------------------+
                                      │
                                      ▼
+-------------------------------------------------------------------------------+
|                          Topological Task Scheduler                           |
+-------------------------------------------------------------------------------+
                                      │
                   ┌──────────────────┴──────────────────┐
                   ▼                                     ▼
        [ Local CAS Cache Hit ]               [ Local CAS Cache Miss ]
                   │                                     │
                   ▼                                     ▼
      Zero-Copy Hard-link Restore              OS Sandbox Process Execution
                   │                                     │
                   └──────────────────┬──────────────────┘
                                      │
                                      ▼
+-------------------------------------------------------------------------------+
|               Signed Provenance Emitter & Deterministic rivox.lock             |
+-------------------------------------------------------------------------------+

---

Installation

Prerequisites

• Rust: 1.75+
• Ecosystem Native Tools:
  • Python: uv (>=0.4.0)
  • Rust: cargo (>=1.75.0)
  • Node.js: pnpm (>=9.0.0)

Pre-built Binary Installation

# macOS / Linux
curl -fsSL https://rivox.dev/install.sh | sh

Build from Source

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

---

Quick Start

1. Initialize rivox.toml in your Monorepo

Create rivox.toml at the root of your 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 Supply-Chain Provenance

rivox verify

---

CLI Reference

Subcommand	Description	Example
rivox build	Coordinates lockfiles, DAG creation, sandboxed compilation, and CAS caching.	rivox build --frozen
rivox cache	Inspects, prunes, or exports local Content-Addressed Storage.	rivox cache status
rivox verify	Validates lockfile parity against native lockfiles and Sigstore signatures.	rivox verify
rivox completions	Generates shell completion scripts (bash, zsh, fish, powershell).	rivox completions zsh

---

Documentation Index

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

---

Roadmap

Phase	Timeline	Deliverables	Status
Phase 1	Aug 2026	Structural Isomorphism Harness, Zero-Copy Lockfile Deserializer, Security Hardening	Completed
Phase 2	Sep–Nov 2026	REAPI Engine, Async Wavefront Scheduler, Go Adapter, Gradle Adapter	Planned
Phase 3	Jan–Jul 2027	Windows Native Sandbox, Distributed CAS Replication, Remote Execution, OCI Support	Planned
Phase 4	Jan–Jun 2028	Incremental Graph Diffing, Policy Engine, Governance, Rivox V3 Release	Research

---

Contributing

We welcome community contributions! Please read our CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting Pull Requests.

---

Security

For security vulnerability disclosures, see SECURITY.md. Please report issues confidentially to aaryan28rwt@gmail.com.

---

License

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

Maintainer: Aaryan Rawat (aaryan28rwt@gmail.com)