tiderace 0.1.0__tar.gz

tiderace-0.1.0/Cargo.toml

@@ -0,0 +1,27 @@
+# Pure-Rust test engine workspace — the tiderace engine.
+#
+# Lives under engine/ (the earlier pytest-orchestrator crate that used to sit at the repo root has been
+# removed). See planning/current/pure-rust-test-engine/ and design/01-architecture.md for the layout.
+[workspace]
+resolver = "2"
+members = ["crates/engine-core", "crates/engine-cli", "crates/engine-daemon"]
+# ② in-process/FFI backend (ADR-E013): a separate optional crate that links libpython (PyO3). Excluded
+# from the default workspace build + the Windows CI job so the core engine stays dependency-free; built
+# explicitly with `PYO3_PYTHON=<python-with-libpython> cargo build --manifest-path crates/engine-inproc/Cargo.toml`.
+exclude = ["crates/engine-inproc", "crates/tiderace-dist"]
+
+[workspace.package]
+edition = "2021"
+version = "0.0.1"
+license = "MIT"
+
+[workspace.dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+thiserror = "2"
+regex = "1"
+# FS watching for the warm daemon (Phase 6, ADR-E007). Same version the legacy crate already vendors.
+notify = "6.1.1"
+
+[profile.release]
+opt-level = 3

tiderace-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: tiderace
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Summary: A pure-Rust test engine for Python — its own runner, not a pytest wrapper.
+Keywords: testing,pytest,rust,test-runner,impact-analysis
+Author: John Aven
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://snoodleboot-io.github.io/tiderace/
+Project-URL: Repository, https://github.com/snoodleboot-io/tiderace
+
+# tiderace
+
+A pure-Rust test engine for Python — its own runner, not a pytest wrapper. Isolation without the fork
+tax, and only runs what changed.
+
+`pip install tiderace` ships the `tiderace` and `tiderace-daemon` binaries plus the native authoring
+package. Docs: https://snoodleboot-io.github.io/tiderace/
+

tiderace-0.1.0/README.md

@@ -0,0 +1,7 @@
+# tiderace
+
+A pure-Rust test engine for Python — its own runner, not a pytest wrapper. Isolation without the fork
+tax, and only runs what changed.
+
+`pip install tiderace` ships the `tiderace` and `tiderace-daemon` binaries plus the native authoring
+package. Docs: https://snoodleboot-io.github.io/tiderace/

tiderace-0.1.0/crates/engine-core/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "engine-core"
+description = "Pure-Rust Python test engine — core library (collection, domain, execution)."
+edition.workspace = true
+version.workspace = true
+license.workspace = true
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+regex = { workspace = true }

tiderace-0.1.0/crates/engine-core/src/cache/cache.rs

@@ -0,0 +1,18 @@
+use crate::cache::{CacheKey, CachedOutcome};
+
+/// The cache seam (ADR-E005): a content-addressed store of test outcomes. Production wires a
+/// [`TieredCache`](crate::cache::TieredCache) (local + optional remote); `--no-cache` / debugging
+/// wires a [`NullCache`](crate::cache::NullCache).
+///
+/// Implementors use interior mutability (`&self` on `put`) so a single cache can be shared across the
+/// worker pool without a `&mut` bottleneck. The orchestrator's preference order is **cache hit →
+/// impact-skip → run** (ADR-E004): consult [`get`](Self::get) first, fall back to impact selection,
+/// then execute and [`put`](Self::put) the fresh outcome.
+pub trait Cache: Send + Sync {
+    /// The cached outcome for `key`, or `None` on a miss.
+    fn get(&self, key: &CacheKey) -> Option<CachedOutcome>;
+
+    /// Store `outcome` under `key`. Callers must only store **pure** outcomes
+    /// (`Purity::is_cacheable`) — impure tests are never silently cached (ADR-E004 soundness).
+    fn put(&self, key: &CacheKey, outcome: CachedOutcome);
+}

tiderace-0.1.0/crates/engine-core/src/cache/cache_key.rs

@@ -0,0 +1,187 @@
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use crate::fixtures::{ClosureHash, ClosureHasher};
+
+/// The content-addressed cache key for one test outcome (ADR-E004): a hash over the test's
+/// *transitive input closure*, so an outcome is a pure function of its inputs and shareable across
+/// machines/CI. Built by [`CacheKeyBuilder`], which composes the ADR's terms:
+///
+/// ```text
+/// key = H( test_identity + executed_source_closure   (from coverage, E006)
+///          + fixture_closure (ClosureHash)           + declared_env
+///          + engine_version + python_version + platform )
+/// ```
+///
+/// Reuses the engine's existing deterministic [`ClosureHasher`] (no new crypto dependency — see its
+/// module note; swap-in point is documented there if collision-resistance is later required).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct CacheKey(ClosureHash);
+
+impl CacheKey {
+    /// Wrap a precomputed digest.
+    pub fn from_hash(h: ClosureHash) -> Self {
+        Self(h)
+    }
+
+    /// The underlying digest.
+    pub fn hash(&self) -> &ClosureHash {
+        &self.0
+    }
+
+    /// Lowercase-hex rendering (the index/diagnostics form).
+    pub fn to_hex(&self) -> String {
+        self.0.to_hex()
+    }
+}
+
+/// Composes a [`CacheKey`] deterministically, independent of call order: environment terms are fed at
+/// construction, the executed-source closure and declared env accumulate into sorted maps, and
+/// [`finish`](Self::finish) feeds everything in a fixed order. The **executed-source closure comes
+/// from coverage** (ADR-E006), not a static guess — that is what makes the cache sound.
+#[derive(Debug, Clone)]
+pub struct CacheKeyBuilder {
+    node_id: String,
+    fixture_closure: Option<ClosureHash>,
+    /// relative source path -> its content hash (sorted for determinism).
+    sources: BTreeMap<PathBuf, [u8; 32]>,
+    /// declared env var -> value (sorted for determinism).
+    env: BTreeMap<String, String>,
+    engine_version: String,
+    python_version: String,
+    platform: String,
+}
+
+impl CacheKeyBuilder {
+    /// Start a key for `node_id`, pinning the environment terms (so a cache built under one
+    /// engine/python/platform never poisons another — ADR-E004 invalidation requirement).
+    pub fn new(
+        node_id: impl Into<String>,
+        engine_version: impl Into<String>,
+        python_version: impl Into<String>,
+        platform: impl Into<String>,
+    ) -> Self {
+        Self {
+            node_id: node_id.into(),
+            fixture_closure: None,
+            sources: BTreeMap::new(),
+            env: BTreeMap::new(),
+            engine_version: engine_version.into(),
+            python_version: python_version.into(),
+            platform: platform.into(),
+        }
+    }
+
+    /// Bind the fixture-closure term (the existing [`ClosureHash`], W14).
+    pub fn fixture_closure(&mut self, h: ClosureHash) -> &mut Self {
+        self.fixture_closure = Some(h);
+        self
+    }
+
+    /// Add one executed source file and its content hash (call once per touched file; order-free).
+    pub fn executed_source(
+        &mut self,
+        path: impl Into<PathBuf>,
+        content_hash: [u8; 32],
+    ) -> &mut Self {
+        self.sources.insert(path.into(), content_hash);
+        self
+    }
+
+    /// Declare an env var the test is allowed to read (part of the closure; order-free).
+    pub fn declared_env(&mut self, key: impl Into<String>, value: impl Into<String>) -> &mut Self {
+        self.env.insert(key.into(), value.into());
+        self
+    }
+
+    /// Finalize into the content-addressed [`CacheKey`].
+    pub fn finish(&self) -> CacheKey {
+        let mut h = ClosureHasher::new();
+        // Domain-separate each section with a tag so a value can't migrate between fields.
+        h.feed_str("engine").feed_str(&self.engine_version);
+        h.feed_str("python").feed_str(&self.python_version);
+        h.feed_str("platform").feed_str(&self.platform);
+        h.feed_str("node").feed_str(&self.node_id);
+        h.feed_str("fixtures").feed(
+            self.fixture_closure
+                .map(|c| *c.as_bytes())
+                .unwrap_or([0u8; 32])
+                .as_slice(),
+        );
+        h.feed_str("sources");
+        for (path, digest) in &self.sources {
+            h.feed(path_bytes(path)).feed(digest);
+        }
+        h.feed_str("env");
+        for (key, value) in &self.env {
+            h.feed_str(key).feed_str(value);
+        }
+        CacheKey::from_hash(h.finish())
+    }
+}
+
+#[cfg(unix)]
+fn path_bytes(p: &Path) -> &[u8] {
+    use std::os::unix::ffi::OsStrExt;
+    p.as_os_str().as_bytes()
+}
+
+#[cfg(not(unix))]
+fn path_bytes(p: &Path) -> &[u8] {
+    // Non-unix: lossy is acceptable — the digest just needs to be stable per-platform, and the
+    // platform term already partitions keys across OSes.
+    p.to_str().unwrap_or("").as_bytes()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn base() -> CacheKeyBuilder {
+        CacheKeyBuilder::new("t.py::a", "0.5.0", "3.12.3", "linux-x86_64")
+    }
+
+    #[test]
+    fn identical_closures_yield_equal_keys() {
+        let a = base().executed_source("src.py", [7u8; 32]).finish();
+        let b = base().executed_source("src.py", [7u8; 32]).finish();
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn source_content_change_changes_key() {
+        let a = base().executed_source("src.py", [7u8; 32]).finish();
+        let b = base().executed_source("src.py", [8u8; 32]).finish();
+        assert_ne!(a, b, "a changed source must miss the cache");
+    }
+
+    #[test]
+    fn env_terms_partition_keys() {
+        let linux = CacheKeyBuilder::new("t.py::a", "0.5.0", "3.12.3", "linux").finish();
+        let mac = CacheKeyBuilder::new("t.py::a", "0.5.0", "3.12.3", "macos").finish();
+        assert_ne!(
+            linux, mac,
+            "platform must partition the cache (no cross-env poisoning)"
+        );
+    }
+
+    #[test]
+    fn source_order_does_not_matter() {
+        let mut a = base();
+        a.executed_source("a.py", [1u8; 32])
+            .executed_source("b.py", [2u8; 32]);
+        let mut b = base();
+        b.executed_source("b.py", [2u8; 32])
+            .executed_source("a.py", [1u8; 32]);
+        assert_eq!(a.finish(), b.finish());
+    }
+
+    #[test]
+    fn fixture_closure_term_participates() {
+        let a = base().finish();
+        let b = base()
+            .fixture_closure(ClosureHash::from_bytes([9u8; 32]))
+            .finish();
+        assert_ne!(a, b);
+    }
+}

tiderace-0.1.0/crates/engine-core/src/cache/cached_outcome.rs

@@ -0,0 +1,33 @@
+use serde::{Deserialize, Serialize};
+
+use crate::domain::Outcome;
+
+/// The stored artifact for one content-addressed test result (ADR-E004): the outcome plus its
+/// captured diagnostics, enough to reconstruct a [`crate::domain::TestResult`] on a cache hit without
+/// re-running the test. (`duration_ms` is intentionally **not** part of the key's identity — it is
+/// recorded for reporting but a hit reports it as cached/zero.)
+///
+/// `Serialize`/`Deserialize` so a shareable tier ([`DirCache`](crate::cache::DirCache)) can persist it
+/// across machines/CI.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CachedOutcome {
+    outcome: Outcome,
+    detail: String,
+}
+
+impl CachedOutcome {
+    pub fn new(outcome: Outcome, detail: impl Into<String>) -> Self {
+        Self {
+            outcome,
+            detail: detail.into(),
+        }
+    }
+
+    pub fn outcome(&self) -> Outcome {
+        self.outcome
+    }
+
+    pub fn detail(&self) -> &str {
+        &self.detail
+    }
+}

tiderace-0.1.0/crates/engine-core/src/cache/dir_cache.rs

@@ -0,0 +1,187 @@
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use crate::cache::{Cache, CacheKey, CachedOutcome};
+
+/// A **directory-backed** cache tier — the shareable remote store (ADR-E004). Each entry is a JSON file
+/// named by the content hash (`<hex>.json`) in `root`, so the store is just a directory: point it at a
+/// CI cache path (`actions/cache`), a shared mount / NFS, or an artifact dir and a green result computed
+/// on one machine is a free hit on any other with the same inputs.
+///
+/// It sits behind the [`Cache`] seam exactly like [`LocalCache`](crate::cache::LocalCache), so
+/// [`TieredCache`](crate::cache::TieredCache)`::with_remote(local, DirCache::new(dir))` gives the
+/// local→remote→backfill flow with zero orchestrator changes. A future HTTP/object-store client is a
+/// drop-in behind the same trait.
+///
+/// **Best-effort by design**: a cache is an optimization, so every I/O error is a silent miss / no-op —
+/// `get`/`put` never panic and never fail a run. Writes are atomic (temp file + rename) so a concurrent
+/// reader (or a killed writer) never observes a half-written entry.
+#[derive(Debug, Clone)]
+pub struct DirCache {
+    root: PathBuf,
+}
+
+/// Process-global counter making each in-flight temp file name unique (multiple threads may write the
+/// same key concurrently; they must not collide on the temp path before the atomic rename).
+static TMP_SEQ: AtomicU64 = AtomicU64::new(0);
+
+impl DirCache {
+    /// Open (and best-effort create) the cache directory at `root`.
+    pub fn new(root: impl Into<PathBuf>) -> Self {
+        let root = root.into();
+        let _ = std::fs::create_dir_all(&root); // get/put tolerate a missing dir anyway
+        Self { root }
+    }
+
+    /// The on-disk path for a key's entry.
+    fn entry_path(&self, key: &CacheKey) -> PathBuf {
+        self.root.join(format!("{}.json", key.to_hex()))
+    }
+
+    /// Number of stored entries (`*.json` files) — diagnostics/tests.
+    pub fn len(&self) -> usize {
+        std::fs::read_dir(&self.root)
+            .map(|rd| {
+                rd.filter_map(|e| e.ok())
+                    .filter(|e| e.path().extension().is_some_and(|x| x == "json"))
+                    .count()
+            })
+            .unwrap_or(0)
+    }
+
+    /// Whether the store has no entries.
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// The directory this cache reads/writes (for diagnostics).
+    pub fn root(&self) -> &Path {
+        &self.root
+    }
+}
+
+impl Cache for DirCache {
+    fn get(&self, key: &CacheKey) -> Option<CachedOutcome> {
+        // A missing file, an unreadable one, or a corrupt/foreign entry all read as a plain miss.
+        let bytes = std::fs::read(self.entry_path(key)).ok()?;
+        serde_json::from_slice(&bytes).ok()
+    }
+
+    fn put(&self, key: &CacheKey, outcome: CachedOutcome) {
+        let Ok(json) = serde_json::to_vec(&outcome) else {
+            return; // unserializable ⇒ just don't cache
+        };
+        // Write to a unique temp file in the same directory, then atomically rename into place, so a
+        // reader never sees a partial entry and two writers of the same key can't corrupt each other.
+        let seq = TMP_SEQ.fetch_add(1, Ordering::Relaxed);
+        let tmp = self.root.join(format!(
+            ".{}.{}.{seq}.tmp",
+            key.to_hex(),
+            std::process::id()
+        ));
+        if std::fs::write(&tmp, &json).is_ok() {
+            if std::fs::rename(&tmp, self.entry_path(key)).is_err() {
+                let _ = std::fs::remove_file(&tmp); // rename failed (e.g. dir vanished) → clean up
+            }
+        } else {
+            let _ = std::fs::remove_file(&tmp);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cache::{CacheKeyBuilder, LocalCache, TieredCache};
+    use crate::domain::Outcome;
+
+    fn key(node: &str) -> CacheKey {
+        CacheKeyBuilder::new(node, "0.5.0", "3.12", "linux").finish()
+    }
+
+    /// A unique temp directory per test (removed on drop).
+    struct TempDir(PathBuf);
+    impl TempDir {
+        fn new(tag: &str) -> Self {
+            static SEQ: AtomicU64 = AtomicU64::new(0);
+            let p = std::env::temp_dir().join(format!(
+                "tiderace_dircache_{tag}_{}_{}",
+                std::process::id(),
+                SEQ.fetch_add(1, Ordering::Relaxed)
+            ));
+            let _ = std::fs::remove_dir_all(&p);
+            Self(p)
+        }
+    }
+    impl Drop for TempDir {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.0);
+        }
+    }
+
+    #[test]
+    fn miss_then_hit_on_disk() {
+        let dir = TempDir::new("hit");
+        let c = DirCache::new(&dir.0);
+        let k = key("t.py::a");
+        assert!(c.get(&k).is_none());
+        c.put(&k, CachedOutcome::new(Outcome::Passed, "ok"));
+        let hit = c.get(&k).expect("hit after put");
+        assert_eq!(hit.outcome(), Outcome::Passed);
+        assert_eq!(hit.detail(), "ok");
+        assert_eq!(c.len(), 1);
+    }
+
+    #[test]
+    fn persists_across_instances_same_dir() {
+        // The "share across machines" property: machine A writes; a fresh cache over the same directory
+        // (machine B, having pulled the CI artifact) reads a hit.
+        let dir = TempDir::new("share");
+        let k = key("t.py::shared");
+        DirCache::new(&dir.0).put(&k, CachedOutcome::new(Outcome::Failed, "boom"));
+
+        let machine_b = DirCache::new(&dir.0); // separate instance, same directory
+        let hit = machine_b.get(&k).expect("cross-instance hit");
+        assert_eq!(hit.outcome(), Outcome::Failed);
+        assert_eq!(hit.detail(), "boom");
+    }
+
+    #[test]
+    fn distinct_keys_do_not_collide() {
+        let dir = TempDir::new("distinct");
+        let c = DirCache::new(&dir.0);
+        c.put(&key("t.py::a"), CachedOutcome::new(Outcome::Passed, ""));
+        c.put(&key("t.py::b"), CachedOutcome::new(Outcome::Failed, "x"));
+        assert_eq!(c.get(&key("t.py::a")).unwrap().outcome(), Outcome::Passed);
+        assert_eq!(c.get(&key("t.py::b")).unwrap().outcome(), Outcome::Failed);
+        assert_eq!(c.len(), 2);
+    }
+
+    #[test]
+    fn corrupt_or_foreign_entry_is_a_miss_not_a_panic() {
+        let dir = TempDir::new("corrupt");
+        let c = DirCache::new(&dir.0);
+        let k = key("t.py::a");
+        std::fs::write(c.entry_path(&k), b"{ not valid json").unwrap();
+        assert!(c.get(&k).is_none(), "corrupt entry reads as a miss");
+    }
+
+    #[test]
+    fn get_on_missing_directory_is_a_miss() {
+        let c = DirCache::new("/nonexistent/tiderace/cache/dir");
+        assert!(c.get(&key("t.py::a")).is_none());
+        // put must not panic even if the directory can't be created/written.
+        c.put(&key("t.py::a"), CachedOutcome::new(Outcome::Passed, ""));
+    }
+
+    #[test]
+    fn tiered_with_dir_remote_backfills_local() {
+        // CI populated the shared dir; a fresh machine's local tier is cold → remote hit → backfill.
+        let dir = TempDir::new("tiered");
+        let k = key("t.py::a");
+        DirCache::new(&dir.0).put(&k, CachedOutcome::new(Outcome::Passed, "")); // "CI" wrote it
+
+        let tiered = TieredCache::with_remote(LocalCache::new(), DirCache::new(&dir.0));
+        assert_eq!(tiered.get(&k).unwrap().outcome(), Outcome::Passed); // local miss → remote hit
+    }
+}

tiderace-0.1.0/crates/engine-core/src/cache/local_cache.rs

@@ -0,0 +1,74 @@
+use std::collections::HashMap;
+use std::sync::Mutex;
+
+use crate::cache::{Cache, CacheKey, CachedOutcome};
+
+/// The local cache tier: an in-process content store keyed by [`CacheKey`]. Backed by a `Mutex`-guarded
+/// map so it satisfies the `Cache: Send + Sync` seam and can be shared across the worker pool.
+///
+/// ADR-E004 specifies a content store + SQLite index on disk for cross-run persistence; this in-memory
+/// store is the faithful `Cache` impl for the warm/inner-loop path and the unit substrate. SQLite-backed
+/// persistence is a drop-in behind the same trait (the `persist`/`load` follow-on).
+#[derive(Debug, Default)]
+pub struct LocalCache {
+    entries: Mutex<HashMap<CacheKey, CachedOutcome>>,
+}
+
+impl LocalCache {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// The number of cached entries (diagnostics/tests).
+    pub fn len(&self) -> usize {
+        self.entries.lock().expect("cache mutex").len()
+    }
+
+    /// Whether the cache is empty.
+    pub fn is_empty(&self) -> bool {
+        self.entries.lock().expect("cache mutex").is_empty()
+    }
+}
+
+impl Cache for LocalCache {
+    fn get(&self, key: &CacheKey) -> Option<CachedOutcome> {
+        self.entries.lock().expect("cache mutex").get(key).cloned()
+    }
+
+    fn put(&self, key: &CacheKey, outcome: CachedOutcome) {
+        self.entries
+            .lock()
+            .expect("cache mutex")
+            .insert(*key, outcome);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cache::CacheKeyBuilder;
+    use crate::domain::Outcome;
+
+    fn key(node: &str) -> CacheKey {
+        CacheKeyBuilder::new(node, "0.5.0", "3.12", "linux").finish()
+    }
+
+    #[test]
+    fn miss_then_hit() {
+        let c = LocalCache::new();
+        let k = key("t.py::a");
+        assert!(c.get(&k).is_none());
+        c.put(&k, CachedOutcome::new(Outcome::Passed, ""));
+        assert_eq!(c.get(&k).unwrap().outcome(), Outcome::Passed);
+        assert_eq!(c.len(), 1);
+    }
+
+    #[test]
+    fn distinct_keys_do_not_collide() {
+        let c = LocalCache::new();
+        c.put(&key("t.py::a"), CachedOutcome::new(Outcome::Passed, ""));
+        c.put(&key("t.py::b"), CachedOutcome::new(Outcome::Failed, "boom"));
+        assert_eq!(c.get(&key("t.py::a")).unwrap().outcome(), Outcome::Passed);
+        assert_eq!(c.get(&key("t.py::b")).unwrap().outcome(), Outcome::Failed);
+    }
+}

tiderace-0.1.0/crates/engine-core/src/cache/mod.rs

@@ -0,0 +1,32 @@
+//! Content-addressed result cache (Phase 5, ADR-E004) — a build-system-for-tests.
+//!
+//! The fastest test is the one never run. Each outcome is modelled as a pure function of its inputs
+//! and stored by content hash, so warm/CI runs approach O(changed tests) and a green result is
+//! shareable across machines. The [`CacheKey`] hashes the test's transitive input closure — crucially
+//! the **executed-source closure from coverage** ([`crate::coverage`]), not a static guess, which is
+//! what makes the cache *sound*. Impure tests are never silently cached ([`Purity`]).
+//!
+//! Seams (ADR-E005): the [`Cache`] trait with [`LocalCache`] + [`TieredCache`] for CI sharing (backed
+//! by a shareable [`DirCache`] remote tier) and [`NullCache`] for debugging. One type per file.
+//!
+//! Orchestrator preference order (ADR-E004): **cache hit → impact-skip → run**.
+
+#[allow(clippy::module_inception)]
+// file name = snake_case of the `Cache` trait (project convention)
+mod cache;
+mod cache_key;
+mod cached_outcome;
+mod dir_cache;
+mod local_cache;
+mod null_cache;
+mod purity;
+mod tiered_cache;
+
+pub use cache::Cache;
+pub use cache_key::{CacheKey, CacheKeyBuilder};
+pub use cached_outcome::CachedOutcome;
+pub use dir_cache::DirCache;
+pub use local_cache::LocalCache;
+pub use null_cache::NullCache;
+pub use purity::{NoSandbox, Purity, SandboxHooks};
+pub use tiered_cache::TieredCache;

tiderace-0.1.0/crates/engine-core/src/cache/null_cache.rs

@@ -0,0 +1,36 @@
+use crate::cache::{Cache, CacheKey, CachedOutcome};
+
+/// A cache that stores nothing and always misses (ADR-E005). Wired by `--no-cache` and used in
+/// debugging / differential runs where every test must actually execute. Lets the orchestrator depend
+/// on the [`Cache`] seam unconditionally instead of branching on an `Option<Cache>`.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NullCache;
+
+impl NullCache {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl Cache for NullCache {
+    fn get(&self, _key: &CacheKey) -> Option<CachedOutcome> {
+        None
+    }
+
+    fn put(&self, _key: &CacheKey, _outcome: CachedOutcome) {}
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cache::CacheKeyBuilder;
+    use crate::domain::Outcome;
+
+    #[test]
+    fn never_stores() {
+        let c = NullCache::new();
+        let k = CacheKeyBuilder::new("t.py::a", "0.5.0", "3.12", "linux").finish();
+        c.put(&k, CachedOutcome::new(Outcome::Passed, ""));
+        assert!(c.get(&k).is_none());
+    }
+}