sui_spec/
lib.rs

1//! sui-spec — declarative Lisp-authored specs for CppNix-parity behaviors.
2//!
3//! ## Why this crate exists
4//!
5//! Every bug we found on the road to drop-in replacement was a *spec*
6//! bug, not an implementation bug.  "Unresolved form has env.out =
7//! ''", "hash the final form not the unresolved one", "mask env
8//! entries whose names match outputs" — these are statements about
9//! CppNix behavior, and they were living inside imperative Rust
10//! functions that happened to be duplicated between the tree-walker
11//! (`sui-eval`) and the bytecode VM (`sui-bytecode`).  The copies
12//! drifted independently.
13//!
14//! This crate is the cure.
15//!
16//! ## The pattern
17//!
18//! > Rust is structure and provability. Lisp is transformation,
19//! > rendering, simulation, and in-flight mutation. The pair can
20//! > **generate each other**: a Rust type is the typed border for
21//! > a Lisp authoring surface; a Lisp spec is the free middle that
22//! > renders out to any morphism (ATerm bytes, JSON attrsets, probe
23//! > matrices) a substrate needs.
24//!
25//! Every domain below is a `#[derive(TataraDomain)]` Rust struct
26//! (the hard, typed border) paired with a `.lisp` spec file (the
27//! free-middle authoring surface).  Interpreters in this crate
28//! consume the typed spec and emit the morphism renderings both
29//! engines call.  Change the Lisp, both engines change together.
30//! The tree-walker and the VM **cannot** diverge because they read
31//! the same authored spec.
32//!
33//! ## Inventory
34//!
35//! - [`derivation`] — input-addressed + fixed-output derivation path
36//!   algorithms.  Was: 50 lines of imperative Rust in each of two
37//!   engines (4 bugs found this session).  Now: one `.lisp` spec
38//!   and one interpreter.
39//! - [`flake`] — top-level flake result shape policy.  Prevents the
40//!   "leak `description` / `nixConfig`" class of bug.
41//! - [`probe`] — single-expression cross-engine parity probes.
42//!   Includes the [`probe::Probe`] type, the original
43//!   `parity_probes.lisp` corpus, and the `builtin_smoke_probes.lisp`
44//!   corpus (one probe per sui builtin module).
45//! - [`rebuild`] — host-aware multi-stage rebuild parity probes.
46//!   The typed substrate that lets `sui-sweep` (and future operator
47//!   surfaces) shadow a real `fleet rebuild` end-to-end without ever
48//!   mutating the system.
49//! - [`parity`] — the [`parity::ParityCheck`] trait every typed
50//!   domain implements, plus [`parity::ShadowReport`] / [`parity::Verdict`]
51//!   / [`parity::ProbeContext`].  This is the second-site abstraction:
52//!   solve once, both [`probe::Probe`] and [`rebuild::RebuildProbe`]
53//!   ride on it, and the future `sui rebuild-shadow` subcommand
54//!   reuses the same trait without re-authoring the sweep loop.
55//! - [`exec`] — typed dual-subprocess runner.  NO SHELL.  Mandatory
56//!   timeout.  Captured output as a typed struct.
57//! - [`sweep`] — library entry point for the shadow-sweep loop.
58//!   Both the `sui-sweep` binary and the `sui rebuild-shadow`
59//!   subcommand (future) wrap [`sweep::run`].
60//!
61//! More domains will land here as we identify them.  Rule of thumb:
62//! if the body of a function is "here is what CppNix does", that
63//! function belongs in this crate as a spec + interpreter, not in
64//! the engine.
65
66pub mod activation_script;
67pub mod ast_evaluator;
68pub mod ast_graph;
69pub mod catalog;
70pub mod cli;
71pub mod cli_coverage;
72pub mod derivation;
73pub mod dockerfile;
74pub mod error;
75pub mod eval_cache;
76pub mod exec;
77pub mod fetcher;
78pub mod flake;
79pub mod gc;
80pub mod hash;
81pub mod loader;
82pub mod lock_file;
83pub mod lockfile_graph;
84pub mod module_compiler;
85pub mod module_graph;
86pub mod module_solver;
87pub mod module_system;
88pub mod nix_replacement_coverage;
89pub mod nar;
90pub mod narinfo;
91pub mod operator_view;
92pub mod parity;
93pub mod store_analyze;
94pub mod store_diff;
95pub mod store_inventory;
96pub mod store_ops;
97pub mod store_query;
98pub mod store_recipe;
99pub mod store_transform;
100pub mod probe;
101pub mod profile;
102pub mod realisation;
103pub mod rebuild;
104pub mod registry;
105pub mod sandbox;
106pub mod spec_trait;
107pub mod store_layout;
108pub mod style;
109pub mod substituter;
110pub mod sweep;
111pub mod trust_model;
112pub mod worker_protocol;
113
114pub use spec_trait::{HasName, Spec};
115
116pub use error::SpecError;
117pub use parity::{ParityCheck, ProbeContext, ProbeKind, ShadowReport, Verdict};
118pub use sweep::{Corpus, SweepConfig};
sui_spec/lib.rs

sui_spec/
lib.rs
