rivox 1.0.0

Universal polyglot build coordination layer for Python, Rust, and Node monorepos
Documentation

Rivox

Universal Polyglot Build Coordination Layer

CI Pipeline Crates.io License: MIT/Apache-2.0 SLSA Level 2

Coordinate. Never Replace.

Overview • Architecture • Quick Start • Supported Ecosystems • CLI Reference • Security Model • Limitations

Table of Contents

  1. Overview
  2. Why Rivox
  3. The Architectural Constitution
  4. Architecture
  5. Supported Ecosystems
  6. Installation
  7. Quick Start
  8. Project Configuration (rivox.toml)
  9. Combined Lockfile (rivox.lock)
  10. Build Workflow
  11. Subtree Content-Addressed Storage (CAS)
  12. Async Wavefront Scheduler
  13. Process Sandboxing
  14. Supply-Chain Provenance & SBOM
  15. CLI Reference
  16. REAPI Remote Execution
  17. OCI Target Exporter
  18. Deterministic Policy Engine
  19. Security Model
  20. Honest Limitations
  21. Frequently Asked Questions (FAQ)
  22. CI/CD Integration
  23. Development & Testing
  24. Roadmap
  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

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

Ecosystem Native Tool Primary Lockfile Adapter Strategy
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

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

Install via Cargo

cargo install --path .

7. Quick Start

1. Initialize rivox.toml

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. Execute Coordinated Build

rivox build

3. Verify Parity & Provenance

rivox verify

8. Project Configuration (rivox.toml)

The rivox.toml file explicitly declares ecosystem root directories and cross-ecosystem build-order dependencies:

[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

Command Subcommand Description 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 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:

[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

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):

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

# 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 OR Apache-2.0.

Maintainer: Aaryan Rawat (aaryan28rwt@gmail.com)