1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
# Rivox System Architecture Specification
**Version**: 1.0.0 (2026)
**Core Motto**: *Coordinate. Never Replace.*
---
## High-Level Architectural Flow
```
+-------------------------------------------------------------------------------+
| User Manifest: rivox.toml |
+-------------------------------------------------------------------------------+
│
▼
+-------------------------------------------------------------------------------+
| Rivox CLI Entry Point |
+-------------------------------------------------------------------------------+
│
▼
+-------------------------------------------------------------------------------+
| Ecosystem Ingestion Adapters |
| ┌───────────────────┬───────────────────┬───────────────────┐ |
| │ Python Adapter │ Rust Adapter │ Node Adapter │ |
| │ (uv lock) │ (cargo metadata) │ (pnpm-lock.yaml) │ |
| └─────────┬─────────┴─────────┬─────────┴─────────┬─────────┘ |
+----------------───┼───────────────────┼───────────────────┼-------------------+
│ │ │
└───────────────────┼───────────────────┘
│
▼
+-------------------------------------------------------------------------------+
| Unified Graph Builder |
+-------------------------------------------------------------------------------+
│
▼
+-------------------------------------------------------------------------------+
| Topological Task Scheduler |
+-------------------------------------------------------------------------------+
│
┌───────────────────┴───────────────────┐
▼ ▼
[ Subtree Cache Hit ] [ Subtree Cache Miss ]
│ │
▼ ▼
Local CAS / REAPI Hard-link OS Sandbox Process Execution
│ │
└───────────────────┬───────────────────┘
│
▼
+-------------------------------------------------------------------------------+
| Local CAS Artifact Store |
+-------------------------------------------------------------------------------+
│
▼
+-------------------------------------------------------------------------------+
| Signed Provenance Emitter |
+-------------------------------------------------------------------------------+
│
▼
+-------------------------------------------------------------------------------+
| Deterministic rivox.lock |
+-------------------------------------------------------------------------------+
```
## Subsystem Responsibilities
1. **Ingestion Layer (`src/adapters/`)**: Wraps `uv`, `cargo`, and `pnpm`. Executes resolution commands in offline/frozen modes and extracts package nodes while preserving target markers and workspace feature unification.
2. **Unified Graph Builder (`src/graph/`)**: Merges subgraphs into a unified DAG (`petgraph::DiGraph`) and binds user-declared `cross_refs`.
3. **Content-Addressed Storage (`src/cache/`)**: Computes Merkle subtree cache keys (`sha256(ecosystem:package:version:merkle_deps:arch)`) and stores file blobs and directory manifest trees (`TreeManifest`).
4. **OS Sandboxing Engine (`src/sandbox/`)**: Isolates build commands using Linux unprivileged user/mount namespaces and macOS Seatbelt (`sandbox-exec`) sandbox profiles.
5. **Provenance Emitter (`src/provenance/`)**: Generates in-toto statements, SLSA Build Level 2 attestations, SPDX 2.3 JSON SBOMs, and Sigstore/Rekor registration.
6. **Equivalence Conformance Suite (`src/conformance/`)**: Automated testing harness checking 100% resolution equivalence against raw native tools.
See also: [design.md](design.md), [cas.md](cas.md), [security.md](security.md).