<div align="center">
# Rivox
### Universal Polyglot Build Coordination Layer
[](https://github.com/Grevix/Rivox/actions/workflows/ci.yml)
[](https://crates.io/crates/rivox)
[](LICENSE)
[](docs/security.md)
**Coordinate. Never Replace.**
[Overview](#1-overview) • [Architecture](#4-architecture) • [Quick Start](#7-quick-start) • [Supported Ecosystems](#5-supported-ecosystems) • [CLI Reference](#15-cli-reference) • [Security Model](#19-security-model) • [Limitations](#20-honest-limitations)
</div>
---
## Table of Contents
1. [Overview](#1-overview)
2. [Why Rivox](#2-why-rivox)
3. [The Architectural Constitution](#3-the-architectural-constitution)
4. [Architecture](#4-architecture)
5. [Supported Ecosystems](#5-supported-ecosystems)
6. [Installation](#6-installation)
7. [Quick Start](#7-quick-start)
8. [Project Configuration (`rivox.toml`)](#8-project-configuration-rivoxtoml)
9. [Combined Lockfile (`rivox.lock`)](#9-combined-lockfile-rivoxlock)
10. [Build Workflow](#10-build-workflow)
11. [Subtree Content-Addressed Storage (CAS)](#11-subtree-content-addressed-storage-cas)
12. [Async Wavefront Scheduler](#12-async-wavefront-scheduler)
13. [Process Sandboxing](#13-process-sandboxing)
14. [Supply-Chain Provenance & SBOM](#14-supply-chain-provenance--sbom)
15. [CLI Reference](#15-cli-reference)
16. [REAPI Remote Execution](#16-reapi-remote-execution)
17. [OCI Target Exporter](#17-oci-target-exporter)
18. [Deterministic Policy Engine](#18-deterministic-policy-engine)
19. [Security Model](#19-security-model)
20. [Honest Limitations](#20-honest-limitations)
21. [Frequently Asked Questions (FAQ)](#21-frequently-asked-questions-faq)
22. [CI/CD Integration](#22-cicd-integration)
23. [Development & Testing](#23-development--testing)
24. [Roadmap](#24-roadmap)
25. [License](#25-license)
---
## 1. Overview
**Rivox** is a lightweight, zero-migration build-coordination and provenance layer for polyglot monorepos containing **Python**, **Rust**, **Node.js**, **Go**, and **Java/Gradle** services.
Instead of requiring engineering teams to rewrite their build pipelines into custom Starlark or Nix derivations (as required by Bazel or Nix), Rivox wraps native ecosystem resolvers (`uv`, `cargo`, `pnpm`, `go`, `gradle`) to construct a unified multigraph, execute sandboxed builds, derive content-addressed cache keys, and emit signed supply-chain attestations.
---
## 2. Why Rivox
Modern engineering teams (50–2,000 engineers) running polyglot monorepos face three recurring pain points:
- **Redundant CI Builds**: Each ecosystem's dependency resolution and build step runs independently without shared caching awareness.
- **Cache Invalidation Cascades**: A change in a single Python file often invalidates unrelated Rust or Node compilation steps in CI.
- **Fragmented Provenance**: Security teams must query pip, npm, crates.io, Go, and Maven trees separately to track CVEs across services.
Rivox fills the gap between hand-rolled CI scripts and full Bazel migrations by coordinating native tools while maintaining zero-copy content-addressed caching across all ecosystems.
---
## 3. 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.
---
## 4. Architecture
```mermaid
flowchart TD
A[rivox.toml Manifest] --> B[Rivox CLI Coordinator]
subgraph Ecosystem Adapters
B --> C1[Python Adapter / uv]
B --> C2[Rust Adapter / cargo]
B --> C3[Node Adapter / pnpm]
B --> C4[Go Adapter / go]
B --> C5[Gradle Adapter / gradle]
end
C1 --> D[Unified Multigraph Builder]
C2 --> D
C3 --> D
C4 --> D
C5 --> D
D --> E[Async Wavefront Scheduler]
E -->|Cache Hit| F[Zero-Copy CAS Restore]
E -->|Cache Miss| G[OS Sandbox Process Execution]
G --> H[Content-Addressed Storage CAS]
G --> I[Signed Provenance Emitter]
F --> J[rivox.lock Manifest]
H --> J
I --> J
```
---
## 5. Supported Ecosystems
| **Python** | `uv` | `uv.lock` | Shells to `uv lock`, parses TOML lockfile, preserves PEP 440 markers. |
| **Rust** | `cargo` | `Cargo.lock` | Parses `Cargo.lock` and runs `cargo metadata` for workspace feature unification. |
| **Node.js** | `pnpm` | `pnpm-lock.yaml` | Parses `pnpm-lock.yaml` and integrates with pnpm's store layout. |
| **Go** | `go` | `go.sum` / `go.mod` | Parses `go.sum` and `go.mod`, computes SHA-256 node content hashes. |
| **Java** | `gradle` | `gradle.lockfile` | Parses `gradle.lockfile` & `build.gradle` project dependency graphs. |
---
## 6. Installation
### Build from Source
```bash
git clone https://github.com/Grevix/Rivox.git
cd Rivox
cargo build --release
sudo cp target/release/rivox /usr/local/bin/
```
### Install via Cargo
```bash
cargo install --path .
```
---
## 7. Quick Start
### 1. Initialize `rivox.toml`
Create `rivox.toml` at the root of your monorepo:
```toml
[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. Execute Coordinated Build
```bash
rivox build
```
### 3. Verify Parity & Provenance
```bash
rivox verify
```
---
## 8. Project Configuration (`rivox.toml`)
The `rivox.toml` file explicitly declares ecosystem root directories and cross-ecosystem build-order dependencies:
```toml
[project]
name = "enterprise-monorepo"
version = "2.1.0"
[ecosystems.python]
path = "services/analytics"
tool = "uv"
[ecosystems.rust]
path = "services/engine"
tool = "cargo"
[ecosystems.node]
path = "services/frontend"
tool = "pnpm"
[ecosystems.go]
path = "services/gateway"
tool = "go"
[ecosystems.gradle]
path = "services/auth"
tool = "gradle"
[[cross_refs]]
consumer = "python:services/analytics"
dependency = "rust:services/engine"
type = "native_extension"
```
---
## 9. Combined Lockfile (`rivox.lock`)
`rivox.lock` is a generated **manifest of native lockfiles**. It records content hashes of authoritative native lockfiles (`uv.lock`, `Cargo.lock`, `pnpm-lock.yaml`, `go.sum`, `gradle.lockfile`) and pins declared `cross_refs` without overriding native version choices.
---
## 10. Build Workflow
1. Read `rivox.toml` manifest.
2. Shell out to native resolvers (`uv`, `cargo`, `pnpm`, `go`, `gradle`).
3. Parse native lockfiles and construct ecosystem subgraphs.
4. Merge subgraphs into a unified DAG using `petgraph::DiGraph` and user `cross_refs`.
5. Schedule build tasks using Kahn's topological sort and Async Wavefront execution levels.
6. Compute Merkle subtree cache keys (`derive_subtree_cache_key`).
7. Check local/remote CAS for cache hits; execute misses inside OS sandboxes.
8. Emit in-toto link metadata, SLSA Build Level 2 claims, and SPDX 2.3 SBOMs.
9. Write `rivox.lock`.
---
## 11. 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`).
---
## 12. Async Wavefront Scheduler
The wavefront scheduler (`plan_wavefronts`) partitions independent DAG nodes into execution levels that can be compiled concurrently without violating build-order constraints.
---
## 13. Process Sandboxing
Build commands run in OS-restricted 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.
---
## 14. 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:...`).
---
## 15. CLI Reference
| `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 step 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` |
---
## 16. REAPI Remote Execution
Rivox integrates with the Remote Execution API (REAPI v2) for remote CAS storage (`bazel-remote`, Buildbarn) and remote action execution runners (`ReapiExecClient`).
---
## 17. 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`.
---
## 18. Deterministic Policy Engine
Machine-readable organization policy rules can be declared in `.rivox/policy.toml`:
```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:
```bash
rivox policy check
```
---
## 19. Security Model
- **No New Trust Roots**: Package trust continues to derive directly from PyPI, crates.io, npm, Go proxies, and Maven repositories.
- **Path Traversal Defenses**: All CAS restores, worker executions, and OCI exports enforce strict path validation (`validate_path_security`).
- **Network Isolation**: Build sandboxes default-deny network access unless explicitly allow-listed in `rivox.toml`.
---
## 20. Honest Limitations
- **No AI in Build Loop**: AI never participates in 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 native build scripts.
- **Native Resolver Dependency**: Native ecosystem tools (`uv`, `cargo`, `pnpm`, `go`, `gradle`) must be installed on the host machine.
---
## 21. 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: Does Rivox require a daemon or server?**
A: No. Rivox is a CLI binary that operates entirely locally or connects to standard REAPI gRPC caches when configured.
---
## 22. CI/CD Integration
Example GitHub Actions workflow (`.github/workflows/ci.yml`):
```yaml
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 uv & pnpm
run: |
pip install uv
npm install -g pnpm
- name: Run Rivox Coordinated Build
run: cargo run -- build --frozen
```
---
## 23. Development & Testing
```bash
# 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
```
---
## 24. Roadmap
- **V1 (Completed)**: Python (`uv`), Rust (`cargo`), Node.js (`pnpm`) adapters, Subtree CAS, OS Sandboxing, Sigstore/Rekor Provenance.
- **V2 (Completed)**: Go adapter, Java/Gradle adapter, Wavefront Parallel Scheduler, CAS LRU Garbage Collector.
- **V3 (Completed)**: Windows process sandboxing, REAPI Remote Execution & Workers, OCI Container Exporter, Incremental Graph Diffing, Policy Engine.
---
## 25. License
Rivox is dual-licensed under [MIT](LICENSE) OR [Apache-2.0](LICENSE).
Maintainer: **Aaryan Rawat** (<aaryan28rwt@gmail.com>)