diff --git a/Cargo.lock b/Cargo.lock
index 245173c..db6d52b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -25,6 +25,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
 dependencies = [
  "cfg-if",
+ "getrandom 0.3.4",
  "once_cell",
  "version_check",
  "zerocopy",
@@ -198,6 +199,7 @@ dependencies = [
  "addr",
  "anyhow",
  "base32",
+ "base58",
  "bimap",
  "blake3",
  "bstr",
@@ -206,6 +208,7 @@ dependencies = [
  "eka-root-macro",
  "gix 0.73.0",
  "hex",
+ "ignore",
  "insta",
  "lazy-regex",
  "nix-compat",
@@ -213,6 +216,7 @@ dependencies = [
  "path-clean 1.0.1",
  "pathdiff",
  "prodash 30.0.1",
+ "resolvo",
  "semver",
  "serde",
  "snix-castore",
@@ -309,12 +313,34 @@ dependencies = [
  "tower-service",
 ]
 
+[[package]]
+name = "base-x"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cbbc9d0964165b47557570cce6c952866c2678457aca742aafc9fb771d30270"
+
+[[package]]
+name = "base256emoji"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5e9430d9a245a77c92176e649af6e275f20839a48389859d1661e9a128d077c"
+dependencies = [
+ "const-str",
+ "match-lookup",
+]
+
 [[package]]
 name = "base32"
 version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "022dfe9eb35f19ebbcb51e0b40a5ab759f46ad60cadf7297e0bd085afb50e076"
 
+[[package]]
+name = "base58"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6107fe1be6682a68940da878d9e9f5e90ca5745b3dec9fd1bb393c8777d4f581"
+
 [[package]]
 name = "base64"
 version = "0.21.7"
@@ -380,8 +406,7 @@ dependencies = [
 [[package]]
 name = "birdcage"
 version = "0.8.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "848df95320021558dd6bb4c26de3fe66724cdcbdbbf3fa720150b52b086ae568"
+source = "git+https://github.com/nrdxp/birdcage?branch=clone_fs#fdcbe8b344bc2ae4d98fedec706644c967d00d35"
 dependencies = [
  "bitflags 2.10.0",
  "libc",
@@ -405,6 +430,18 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "bitvec"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc2832c24239b0141d5674bb9174f9d68a8b5b3f2753311927c172ca46f7e9c"
+dependencies = [
+ "funty",
+ "radium",
+ "tap",
+ "wyz",
+]
+
 [[package]]
 name = "blake3"
 version = "1.8.2"
@@ -652,6 +689,15 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e47641d3deaf41fb1538ac1f54735925e275eaf3bf4d55c81b137fba797e5cbb"
 
+[[package]]
+name = "concurrent-queue"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
+dependencies = [
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "config"
 version = "0.1.0"
@@ -694,6 +740,12 @@ version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 
+[[package]]
+name = "const-str"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f421161cb492475f1661ddc9815a745a1c894592070661180fdec3d4872e9c3"
+
 [[package]]
 name = "constant_time_eq"
 version = "0.3.1"
@@ -825,6 +877,12 @@ dependencies = [
  "crossterm",
 ]
 
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
 [[package]]
 name = "crypto-common"
 version = "0.1.6"
@@ -952,6 +1010,26 @@ version = "2.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2a2330da5de22e8a3cb63252ce2abb30116bf5265e89c0e01bc17015ce30a476"
 
+[[package]]
+name = "data-encoding-macro"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47ce6c96ea0102f01122a185683611bd5ac8d99e62bc59dd12e6bda344ee673d"
+dependencies = [
+ "data-encoding",
+ "data-encoding-macro-internal",
+]
+
+[[package]]
+name = "data-encoding-macro-internal"
+version = "0.1.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d162beedaa69905488a8da94f5ac3edb4dd4788b732fadb7bd120b2625c1976"
+dependencies = [
+ "data-encoding",
+ "syn 2.0.109",
+]
+
 [[package]]
 name = "der"
 version = "0.7.10"
@@ -1123,9 +1201,13 @@ dependencies = [
  "anyhow",
  "atom",
  "clap",
+ "config",
  "either",
  "gix 0.73.0",
+ "json-digest",
+ "nixec",
  "semver",
+ "serde_json",
  "tempfile",
  "thiserror 2.0.17",
  "tokio",
@@ -1146,6 +1228,15 @@ dependencies = [
  "syn 2.0.109",
 ]
 
+[[package]]
+name = "elsa"
+version = "1.11.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9abf33c656a7256451ebb7d0082c5a471820c31269e49d807c538c252352186e"
+dependencies = [
+ "stable_deref_trait",
+]
+
 [[package]]
 name = "encode_unicode"
 version = "0.3.6"
@@ -1210,6 +1301,17 @@ dependencies = [
  "windows-sys 0.61.1",
 ]
 
+[[package]]
+name = "event-listener"
+version = "5.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13b66accf52311f30a0db42147dadea9850cb48cd070028831ae5f5d4b856ab"
+dependencies = [
+ "concurrent-queue",
+ "parking",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "fastcdc"
 version = "3.2.1"
@@ -1328,6 +1430,12 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "funty"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
+
 [[package]]
 name = "fuse-backend-rs"
 version = "0.12.1"
@@ -3504,6 +3612,19 @@ dependencies = [
  "thiserror 2.0.17",
 ]
 
+[[package]]
+name = "globset"
+version = "0.4.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52dfc19153a48bde0cbd630453615c8151bce3a5adfac7a0aebfbf0a1e1f57e3"
+dependencies = [
+ "aho-corasick",
+ "bstr",
+ "log",
+ "regex-automata",
+ "regex-syntax",
+]
+
 [[package]]
 name = "h2"
 version = "0.4.12"
@@ -3936,6 +4057,22 @@ dependencies = [
  "icu_properties",
 ]
 
+[[package]]
+name = "ignore"
+version = "0.4.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3d782a365a015e0f5c04902246139249abf769125006fbe7649e2ee88169b4a"
+dependencies = [
+ "crossbeam-deque",
+ "globset",
+ "log",
+ "memchr",
+ "regex-automata",
+ "same-file",
+ "walkdir",
+ "winapi-util",
+]
+
 [[package]]
 name = "imara-diff"
 version = "0.1.8"
@@ -4159,6 +4296,21 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "json-digest"
+version = "0.0.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7196711951c49c12eb01341a7ff9b85fddae7fa9fbdcdd48e93a451953618aef"
+dependencies = [
+ "anyhow",
+ "multibase",
+ "rand 0.8.5",
+ "serde",
+ "serde_json",
+ "tiny-keccak",
+ "unicode-normalization",
+]
+
 [[package]]
 name = "kstring"
 version = "2.0.2"
@@ -4390,6 +4542,17 @@ version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
 
+[[package]]
+name = "match-lookup"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1265724d8cb29dbbc2b0f06fffb8bf1a8c0cf73a78eede9ba73a4a66c52a981e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "matchers"
 version = "0.2.0"
@@ -4551,6 +4714,18 @@ dependencies = [
  "windows-sys 0.61.1",
 ]
 
+[[package]]
+name = "multibase"
+version = "0.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8694bb4835f452b0e3bb06dbebb1d6fc5385b6ca1caf2e55fd165c042390ec77"
+dependencies = [
+ "base-x",
+ "base256emoji",
+ "data-encoding",
+ "data-encoding-macro",
+]
+
 [[package]]
 name = "multimap"
 version = "0.10.1"
@@ -4642,6 +4817,7 @@ dependencies = [
 name = "nixec"
 version = "0.1.0"
 dependencies = [
+ "anyhow",
  "birdcage",
  "thiserror 2.0.17",
 ]
@@ -4798,6 +4974,12 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "parking"
+version = "2.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba"
+
 [[package]]
 name = "parking_lot"
 version = "0.12.5"
@@ -4888,6 +5070,18 @@ dependencies = [
  "indexmap 2.12.0",
 ]
 
+[[package]]
+name = "petgraph"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8701b58ea97060d5e5b155d383a69952a60943f0e6dfe30b04c287beb0b27455"
+dependencies = [
+ "fixedbitset 0.5.7",
+ "hashbrown 0.15.5",
+ "indexmap 2.12.0",
+ "serde",
+]
+
 [[package]]
 name = "pin-project"
 version = "1.1.10"
@@ -5312,6 +5506,12 @@ version = "5.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
 
+[[package]]
+name = "radium"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"
+
 [[package]]
 name = "radix_trie"
 version = "0.2.1"
@@ -5577,6 +5777,23 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "resolvo"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "670175f9a825ad2419bea0e14bfe74e5dcc0227ec7a652a655b1c11e2b911754"
+dependencies = [
+ "ahash",
+ "bitvec",
+ "elsa",
+ "event-listener",
+ "futures",
+ "indexmap 2.12.0",
+ "itertools 0.14.0",
+ "petgraph 0.8.3",
+ "tracing",
+]
+
 [[package]]
 name = "ring"
 version = "0.17.14"
@@ -5644,7 +5861,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys 0.4.15",
- "windows-sys 0.59.0",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -5854,6 +6071,7 @@ version = "1.0.145"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "402a6f66d8c709116cf22f558eab210f5a50187f702eb4d7e5ef38d9a7f1c79c"
 dependencies = [
+ "indexmap 2.12.0",
  "itoa",
  "memchr",
  "ryu",
@@ -6546,6 +6764,12 @@ dependencies = [
  "unicode-width 0.2.1",
 ]
 
+[[package]]
+name = "tap"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
+
 [[package]]
 name = "tar"
 version = "0.4.44"
@@ -6697,6 +6921,15 @@ dependencies = [
  "time-core",
 ]
 
+[[package]]
+name = "tiny-keccak"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c9d3793400a45f954c52e73d068316d76b6f4e36977e3fcebb13a2721e80237"
+dependencies = [
+ "crunchy",
+]
+
 [[package]]
 name = "tinystr"
 version = "0.8.2"
@@ -7712,15 +7945,6 @@ dependencies = [
  "windows-targets 0.52.6",
 ]
 
-[[package]]
-name = "windows-sys"
-version = "0.59.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
-dependencies = [
- "windows-targets 0.52.6",
-]
-
 [[package]]
 name = "windows-sys"
 version = "0.60.2"
@@ -7969,6 +8193,15 @@ name = "wu-manber"
 version = "0.1.0"
 source = "git+https://github.com/tvlfyi/wu-manber.git#0d5b22bea136659f7de60b102a7030e0daaa503d"
 
+[[package]]
+name = "wyz"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05f360fc0b24296329c78fda852a1e9ae82de9cf7b27dae4b7f62f118f77b9ed"
+dependencies = [
+ "tap",
+]
+
 [[package]]
 name = "xattr"
 version = "1.6.1"
diff --git a/Cargo.toml b/Cargo.toml
index e187c9a..4c85c2a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -13,7 +13,7 @@ version = "0.3.0"
 [profile.release]
 codegen-units = 1
 lto           = true
-opt-level     = 3
+opt-level     = "z"
 strip         = true
 
 [dependencies]
@@ -32,7 +32,12 @@ tracing-appender.workspace   = true
 tracing-indicatif.workspace  = true
 tracing-subscriber.workspace = true
 
-atom.path = "crates/atom"
+atom.path   = "crates/atom"
+config.path = "crates/config"
+nixec.path  = "crates/nixec"
+
+json-digest = "0.0.16"
+serde_json  = "1.0.145"
 
 [workspace.dependencies]
 anyhow                = "^1"
@@ -83,6 +88,7 @@ prodash = { version = "30.0.1", features = [
 ] }
 
 [patch.crates-io]
+birdcage           = { git = "https://github.com/nrdxp/birdcage", branch = "clone_fs" }
 tracing            = { git = "https://github.com/nrdxp/tracing", branch = "hierarchical" }
 tracing-appender   = { git = "https://github.com/nrdxp/tracing", branch = "hierarchical" }
 tracing-core       = { git = "https://github.com/nrdxp/tracing", branch = "hierarchical" }
diff --git a/adrs/0015-sat-resolution-implementation.md b/adrs/0015-sat-resolution-implementation.md
new file mode 100644
index 0000000..f52d2da
--- /dev/null
+++ b/adrs/0015-sat-resolution-implementation.md
@@ -0,0 +1,1533 @@
+# ADR-0015: SAT-Based Transitive Resolution Implementation Plan
+
+## Status
+
+Draft - Ready for Implementation
+
+## Abstract
+
+This ADR provides the detailed implementation plan for transitioning eka from direct-dependency-only resolution to full SAT-based transitive resolution using the resolvo crate. It builds upon ADR-0014's architectural decisions and specifies explicit algorithms, data structures, and integration points.
+
+---
+
+## Part 1: Executive Summary
+
+### 1.1 Current State
+
+The current resolution system (`crates/atom/src/package/resolve/mod.rs`) only resolves direct dependencies:
+
+```rust
+// Current: Only processes manifest's direct deps
+fn synchronize_atoms(&mut self, manifest: &ValidManifest) -> Result<(), DocError> {
+    for (set_tag, set) in manifest.as_ref().deps().from() {
+        for (label, req) in set {
+            self.synchronize_atom(req.to_owned(), id.to_owned(), set_tag.to_owned())?;
+        }
+    }
+}
+```
+
+### 1.2 Target State
+
+Full transitive resolution with lazy manifest fetching:
+- SAT solver determines globally consistent version selection
+- Manifests fetched only when SAT solver needs dependency information
+- Complete transitive closure captured in lock file v2
+- Per-dependency `requires` field enables graph reconstruction
+
+### 1.3 Key Design Decisions
+
+1. **Use resolvo's CDCL SAT solver** - Production-tested, async-native, supports lazy clause generation
+2. **Implement custom `AtomDependencyProvider`** - Maps atom semantics to resolvo's trait
+3. **Leverage `hint_dependencies_available`** - Signal cached vs requires-fetch atoms
+4. **Cheap ref queries for candidate discovery** - Use `gix::Url::get_refs()` (metadata only)
+5. **Lazy manifest fetch for dependencies** - Only fetch when solver needs deps
+
+---
+
+## Part 2: Data Structure Design
+
+### 2.1 Atom Identity Mapping
+
+**Problem**: Resolvo uses `NameId` for packages and `SolvableId` for versions. Atoms have two-level identity: `(Root, Label)`.
+
+**Solution**: Use the existing `AtomId<Root>` type directly as the package name:
+
+```rust
+// AtomId<Root> already captures (Root, Label) - no need for a new type
+// The existing implementation in crates/atom/src/id/mod.rs works perfectly:
+//
+// pub struct AtomId<R> {
+//     root: R,
+//     label: Label,
+// }
+//
+// It implements Clone + PartialEq + Eq + Hash via derives,
+// satisfying resolvo's PackageName trait requirements.
+
+// For display in error messages:
+impl<R: std::fmt::Display> std::fmt::Display for AtomId<R> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}::{}", self.root, self.label)
+    }
+}
+```
+
+The existing `AtomId<Root>` already has the right semantics:
+- `Root` = genesis commit hash (repository identity)
+- `Label` = atom name within that repository
+- Implements `Clone + Eq + Hash` as required by resolvo's `PackageName` trait
+
+### 2.2 Version Set Implementation
+
+**Problem**: Resolvo's `VersionSet` trait requires `Clone + Eq + Hash`. Semver ranges satisfy this.
+
+**Solution**: Use `semver::VersionReq` directly as the version set:
+
+```rust
+/// Wrapper for semver::VersionReq that implements resolvo's VersionSet trait
+#[derive(Clone, PartialEq, Eq, Hash)]
+pub struct SemverVersionSet(pub semver::VersionReq);
+
+impl resolvo::utils::VersionSet for SemverVersionSet {
+    type V = semver::Version;
+}
+
+impl SemverVersionSet {
+    pub fn matches(&self, version: &semver::Version) -> bool {
+        self.0.matches(version)
+    }
+}
+```
+
+### 2.3 Solvable Record Type
+
+Each solvable (specific version of an atom) needs associated metadata:
+
+```rust
+/// Metadata for a specific atom version in the resolver pool
+#[derive(Clone, Debug)]
+pub struct AtomSolvableRecord {
+    /// The concrete semantic version
+    pub version: semver::Version,
+    /// Git revision (commit hash) for this version
+    pub rev: metadata::GitDigest,
+    /// Whether we have the manifest cached (deps available without fetch)
+    pub manifest_cached: bool,
+    /// Machine-computed atom ID for verification
+    pub atom_id: id::AtomDigest,
+}
+```
+
+### 2.4 Lock File v2 Format
+
+Extend `AtomDep` with transitive dependency information. Key changes from v1:
+- **Remove `mirror` field** - nix reads from local store only (per ADR-0014)
+- **`requires` uses `AtomDigest`** - concise reference by computed hash
+- **Add `direct` flag** - distinguishes root's direct deps from transitives
+
+```rust
+/// Represents a locked atom dependency with its own requirements
+#[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, PartialOrd, Ord)]
+#[serde(deny_unknown_fields)]
+pub struct AtomDepV2 {
+    /// The unique identifier of the atom
+    label: Label,
+    /// The semantic version of the atom
+    version: Version,
+    /// Repository identity (root hash)
+    set: GitDigest,
+    /// Git revision (commit hash) for verification
+    rev: GitDigest,
+    /// Machine-computed cryptographic identity (BLAKE3 hash of AtomId)
+    id: AtomDigest,
+    /// NEW: Direct dependencies of this atom, referenced by their AtomDigest
+    /// Enables transitive closure reconstruction as a hypergraph
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    requires: Vec<AtomDigest>,
+    /// NEW: Whether this is a direct dependency of the root manifest
+    #[serde(default, skip_serializing_if = "crate::package::metadata::manifest::not")]
+    direct: bool,
+}
+
+// Note: AtomRef removed - we use AtomDigest directly for conciseness
+// The AtomDigest uniquely identifies an atom and can be looked up in the deps table
+
+/// Lock file with version field for migration
+#[derive(Serialize, Deserialize, Debug, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct LockfileV2 {
+    /// Schema version - 2 for transitive resolution
+    pub version: u16,
+    /// Set definitions with mirrors (used during resolution/store population only)
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub sets: BTreeMap<GitDigest, SetDetails>,
+    /// Composer configuration
+    pub compose: Using,
+    /// Full transitive closure of dependencies
+    #[serde(default, skip_serializing_if = "DepMap::is_empty")]
+    pub deps: DepMap<Root, Dep>,
+}
+```
+
+**Lock file v2 as hypergraph**: The structure naturally encodes a directed hypergraph where:
+- **Nodes**: `AtomDigest` values (each resolved atom)
+- **Edges**: Each dep's `requires` field forms hyperedges from that atom to its dependencies
+
+This can be deserialized into `hyperdep::HyperGraph<AtomDigest, ()>` for traversal operations like topological sorting, cycle detection, and impact analysis.
+
+---
+
+## Part 3: AtomDependencyProvider Implementation
+
+### 3.1 Core State Structure
+
+```rust
+/// Resolution context holding all state needed for dependency resolution
+pub struct AtomResolver<'a, S: LocalStorage> {
+    /// The resolvo pool for interning - uses AtomId<Root> directly as package name
+    pool: Pool<SemverVersionSet, AtomId<Root>>,
+    
+    /// Mapping from AtomId to available versions discovered via ref queries
+    discovered_candidates: HashMap<AtomId<Root>, Vec<DiscoveredVersion>>,
+    
+    /// Cache of fetched manifests: (AtomId, Version) -> parsed dependencies
+    manifest_cache: HashMap<(AtomId<Root>, Version), Vec<AtomDependency>>,
+    
+    /// Set of solvables whose manifests are locally cached (cheap deps access)
+    locally_available: HashSet<SolvableId>,
+    
+    /// Reference to resolved sets from manifest processing
+    resolved_sets: &'a ResolvedSets<'a, S>,
+    
+    /// Storage backend for git operations
+    storage: &'a S,
+    
+    /// Transports for remote operations (reusable connections)
+    transports: HashMap<gix::Url, Box<dyn Transport + Send>>,
+}
+
+#[derive(Clone, Debug)]
+struct DiscoveredVersion {
+    version: Version,
+    rev: GitDigest,
+    solvable_id: SolvableId,
+}
+
+#[derive(Clone, Debug)]
+struct AtomDependency {
+    /// Target atom identity (Root + Label)
+    target: AtomId<Root>,
+    /// Version requirement
+    version_req: VersionReq,
+}
+```
+
+### 3.2 DependencyProvider Implementation
+
+```rust
+impl<'a, S: LocalStorage> DependencyProvider for AtomResolver<'a, S> {
+    /// Filter candidates by checking if version satisfies the version set
+    async fn filter_candidates(
+        &self,
+        candidates: &[SolvableId],
+        version_set: VersionSetId,
+        inverse: bool,
+    ) -> Vec<SolvableId> {
+        let vs = self.pool.resolve_version_set(version_set);
+        candidates
+            .iter()
+            .filter(|&&solvable_id| {
+                let solvable = self.pool.resolve_solvable(solvable_id);
+                let matches = vs.matches(&solvable.record.version);
+                if inverse { !matches } else { matches }
+            })
+            .copied()
+            .collect()
+    }
+
+    /// Get all candidate versions for a package
+    /// This uses CHEAP ref queries - no manifest fetching
+    async fn get_candidates(&self, name: NameId) -> Option<Candidates> {
+        let package_name = self.pool.resolve_package_name(name);
+        
+        // Check if we've already discovered candidates for this package
+        if let Some(versions) = self.discovered_candidates.get(package_name) {
+            let candidate_ids: Vec<SolvableId> = versions
+                .iter()
+                .map(|v| v.solvable_id)
+                .collect();
+            
+            // Build hint_dependencies_available bitmap
+            let available_bitmap = self.build_availability_bitmap(&candidate_ids);
+            
+            return Some(Candidates {
+                candidates: candidate_ids,
+                favored: None,
+                locked: None,
+                hint_dependencies_available: available_bitmap,
+                excluded: vec![],
+            });
+        }
+        
+        // Need to discover candidates via cheap ref query
+        match self.discover_candidates_for_package(package_name).await {
+            Ok(candidates) => Some(candidates),
+            Err(e) => {
+                tracing::warn!(
+                    package = %package_name,
+                    error = %e,
+                    "failed to discover candidates"
+                );
+                None
+            }
+        }
+    }
+
+    /// Sort candidates by version descending (latest first)
+    async fn sort_candidates(
+        &self,
+        _solver: &resolvo::SolverCache<Self>,
+        solvables: &mut [SolvableId],
+    ) {
+        solvables.sort_by(|&a, &b| {
+            let va = &self.pool.resolve_solvable(a).record.version;
+            let vb = &self.pool.resolve_solvable(b).record.version;
+            vb.cmp(va) // Descending order: latest first
+        });
+    }
+
+    /// Get dependencies for a specific solvable
+    /// This is where LAZY MANIFEST FETCHING happens
+    async fn get_dependencies(&self, solvable: SolvableId) -> Dependencies {
+        let solvable_data = self.pool.resolve_solvable(solvable);
+        let package_name = self.pool.resolve_package_name(solvable_data.name);
+        let version = &solvable_data.record.version;
+        
+        // Check manifest cache first
+        let cache_key = (package_name.clone(), version.clone());
+        if let Some(deps) = self.manifest_cache.get(&cache_key) {
+            return self.convert_deps_to_resolvo(deps);
+        }
+        
+        // Need to fetch manifest - this is the expensive operation
+        match self.fetch_and_parse_manifest(package_name, version).await {
+            Ok(deps) => {
+                // Cache for future use
+                self.manifest_cache.insert(cache_key, deps.clone());
+                self.convert_deps_to_resolvo(&deps)
+            }
+            Err(e) => {
+                let reason = self.pool.intern_string(format!(
+                    "manifest fetch failed: {}",
+                    e
+                ));
+                Dependencies::Unknown(reason)
+            }
+        }
+    }
+}
+```
+
+### 3.3 Candidate Discovery (Cheap Ref Query)
+
+```rust
+impl<'a, S: LocalStorage> AtomResolver<'a, S> {
+    /// Discover available versions for a package using cheap ref queries
+    /// This does NOT fetch manifests - only refs
+    async fn discover_candidates_for_package(
+        &mut self,
+        package: &AtomId<Root>,
+    ) -> Result<Candidates, BoxError> {
+        // Construct ref query pattern: refs/eka/atoms/<label>/*
+        let ref_pattern = format!(
+            "{}/*:{}/*",
+            format!("{}/{}", crate::ATOM_REFS.as_str(), package.label()),
+            format!("{}/{}", crate::ATOM_REFS.as_str(), package.label()),
+        );
+        
+        // Get URL for this package's repository from resolved sets
+        let mirror_url = self.get_mirror_for_root(package.root())?;
+        
+        // Cheap ref query via gix::Url (metadata only, no git objects)
+        let transport = self.transports.get_mut(&mirror_url);
+        let refs = mirror_url.get_refs([ref_pattern.as_str()], transport)?;
+        
+        // Parse refs into versions
+        let mut versions = Vec::new();
+        let name_id = self.pool.intern_package_name(package.clone());
+        
+        for r in refs {
+            if let Some((version, rev)) = self.parse_atom_ref(&r, package.label()) {
+                let record = AtomSolvableRecord {
+                    version: version.clone(),
+                    rev,
+                    manifest_cached: self.is_manifest_cached(package, &version),
+                    atom_id: package.compute_hash(),
+                };
+                
+                let solvable_id = self.pool.intern_solvable(name_id, record);
+                
+                versions.push(DiscoveredVersion {
+                    version,
+                    rev,
+                    solvable_id,
+                });
+            }
+        }
+        
+        // Cache discovered versions
+        self.discovered_candidates.insert(package.clone(), versions.clone());
+        
+        // Build result
+        let candidate_ids: Vec<_> = versions.iter().map(|v| v.solvable_id).collect();
+        let available_bitmap = self.build_availability_bitmap(&candidate_ids);
+        
+        Ok(Candidates {
+            candidates: candidate_ids,
+            favored: None,
+            locked: None,  // TODO: Check if version is already locked
+            hint_dependencies_available: available_bitmap,
+            excluded: vec![],
+        })
+    }
+    
+    /// Parse an atom ref like "refs/eka/atoms/foo/1.2.3" into (Version, Rev)
+    fn parse_atom_ref(
+        &self,
+        r: &gix::protocol::handshake::Ref,
+        expected_label: &Label,
+    ) -> Option<(Version, GitDigest)> {
+        use bstr::ByteSlice;
+        
+        let (name, id, ..) = r.unpack();
+        let name_str = name.to_str().ok()?;
+        
+        // Expected format: refs/eka/atoms/<label>/<version>
+        let prefix = format!("{}/{}/", crate::ATOM_REFS.as_str(), expected_label);
+        let version_str = name_str.strip_prefix(&prefix)?;
+        
+        let version = Version::parse(version_str).ok()?;
+        let rev = match id {
+            gix::ObjectId::Sha1(bytes) => GitDigest::Sha1(*bytes),
+        };
+        
+        Some((version, rev))
+    }
+    
+    /// Build availability bitmap based on which manifests are locally cached
+    fn build_availability_bitmap(&self, solvables: &[SolvableId]) -> HintDependenciesAvailable {
+        if solvables.is_empty() {
+            return HintDependenciesAvailable::None;
+        }
+        
+        let all_available = solvables.iter().all(|id| self.locally_available.contains(id));
+        let any_available = solvables.iter().any(|id| self.locally_available.contains(id));
+        
+        if all_available {
+            HintDependenciesAvailable::All
+        } else if any_available {
+            // Build specific bitmap
+            let mut indices = Vec::new();
+            for (idx, id) in solvables.iter().enumerate() {
+                if self.locally_available.contains(id) {
+                    indices.push(idx as u32);
+                }
+            }
+            HintDependenciesAvailable::Some(indices.into())
+        } else {
+            HintDependenciesAvailable::None
+        }
+    }
+}
+```
+
+### 3.4 Manifest Fetching (Lazy, On-Demand)
+
+```rust
+impl<'a, S: LocalStorage> AtomResolver<'a, S> {
+    /// Fetch and parse manifest for a specific atom version
+    /// This is the EXPENSIVE operation - deferred until SAT solver needs deps
+    async fn fetch_and_parse_manifest(
+        &mut self,
+        package: &AtomId<Root>,
+        version: &Version,
+    ) -> Result<Vec<AtomDependency>, BoxError> {
+        tracing::debug!(
+            package = %package,
+            version = %version,
+            "fetching manifest (lazy)"
+        );
+        
+        // Get mirror URL
+        let mirror_url = self.get_mirror_for_root(package.root())?;
+        
+        // Fetch the atom commit
+        let atom_ref = format!(
+            "{}/{}/{}",
+            crate::ATOM_REFS.as_str(),
+            package.label(),
+            version
+        );
+        
+        // This fetches git objects - the expensive part
+        let cache_repo = storage::git::cache::repo()?;
+        let local_repo = cache_repo.to_thread_local();
+        let transport = self.transports.get_mut(&mirror_url);
+        
+        let (root, mut remote) = local_repo.ensure_remote(&mirror_url, transport)?;
+        let commit = local_repo.resolve_atom_to_cache(
+            &mut (root, remote),
+            package.label(),
+            version,
+            transport,
+        )?;
+        
+        // Parse manifest from commit tree
+        let tree = commit.tree()?;
+        let manifest_entry = tree.lookup_entry_by_path(crate::ATOM_MANIFEST_NAME.as_str())?
+            .ok_or("atom.toml not found in commit")?;
+        
+        let blob = local_repo.find_object(manifest_entry.object_id())?.into_blob();
+        let manifest_str = std::str::from_utf8(&blob.data)?;
+        let manifest: ValidManifest = toml_edit::de::from_str(manifest_str)?;
+        
+        // Extract dependencies
+        let mut deps = Vec::new();
+        for (set_tag, set_deps) in manifest.as_ref().deps().from() {
+            // Resolve set tag to root hash
+            if let Some(set_root) = self.resolve_set_tag_to_root(set_tag) {
+                for (label, version_req) in set_deps {
+                    deps.push(AtomDependency {
+                        target: AtomId::from((set_root, label.clone())),
+                        version_req: version_req.clone(),
+                    });
+                }
+            }
+        }
+        
+        // Mark this solvable as now having deps available
+        if let Some(versions) = self.discovered_candidates.get(package) {
+            for v in versions {
+                if &v.version == version {
+                    self.locally_available.insert(v.solvable_id);
+                    break;
+                }
+            }
+        }
+        
+        Ok(deps)
+    }
+    
+    /// Convert parsed dependencies to resolvo's format
+    fn convert_deps_to_resolvo(&self, deps: &[AtomDependency]) -> Dependencies {
+        let requirements: Vec<ConditionalRequirement> = deps
+            .iter()
+            .filter_map(|dep| {
+                let name_id = self.pool.lookup_package_name(&dep.target)?;
+                let version_set = SemverVersionSet(dep.version_req.clone());
+                let vs_id = self.pool.intern_version_set(name_id, version_set);
+                
+                Some(ConditionalRequirement {
+                    condition: None,
+                    requirement: Requirement::Single(vs_id),
+                })
+            })
+            .collect();
+        
+        Dependencies::Known(KnownDependencies {
+            requirements,
+            constrains: vec![],
+        })
+    }
+}
+```
+
+### 3.5 Interner Implementation
+
+```rust
+impl<'a, S: LocalStorage> Interner for AtomResolver<'a, S> {
+    fn display_solvable(&self, solvable: SolvableId) -> impl std::fmt::Display + '_ {
+        let solvable = self.pool.resolve_solvable(solvable);
+        let name = self.pool.resolve_package_name(solvable.name);
+        format!("{}@{}", name, solvable.record.version)
+    }
+
+    fn display_name(&self, name: NameId) -> impl std::fmt::Display + '_ {
+        self.pool.resolve_package_name(name).to_string()
+    }
+
+    fn display_version_set(&self, version_set: VersionSetId) -> impl std::fmt::Display + '_ {
+        self.pool.resolve_version_set(version_set).0.to_string()
+    }
+
+    fn display_string(&self, string_id: StringId) -> impl std::fmt::Display + '_ {
+        self.pool.resolve_string(string_id).to_string()
+    }
+
+    fn version_set_name(&self, version_set: VersionSetId) -> NameId {
+        self.pool.resolve_version_set_package_name(version_set)
+    }
+
+    fn solvable_name(&self, solvable: SolvableId) -> NameId {
+        self.pool.resolve_solvable(solvable).name
+    }
+
+    fn version_sets_in_union(
+        &self,
+        version_set_union: VersionSetUnionId,
+    ) -> impl Iterator<Item = VersionSetId> {
+        self.pool.resolve_version_set_union(version_set_union)
+    }
+
+    fn resolve_condition(&self, condition: ConditionId) -> Condition {
+        self.pool.resolve_condition(condition).clone()
+    }
+}
+```
+
+---
+
+## Part 4: Resolution Algorithm
+
+### 4.1 High-Level Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         RESOLUTION FLOW                                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  1. INITIALIZATION                                                           │
+│     ├── Read root manifest (atom.toml)                                       │
+│     ├── Create AtomResolver with empty caches                                │
+│     └── Build initial Problem from root's direct deps                        │
+│                                                                              │
+│  2. CANDIDATE DISCOVERY (cheap ref queries)                                  │
+│     ├── For each required package, query refs/eka/atoms/<label>/*            │
+│     ├── Parse versions from ref names                                        │
+│     ├── Intern into pool as SolvableIds                                      │
+│     └── Set hint_dependencies_available based on cache state                 │
+│                                                                              │
+│  3. SAT SOLVING (resolvo CDCL)                                               │
+│     ├── Solver picks variable (package) with smallest domain                 │
+│     ├── Solver picks value (version) - latest first                          │
+│     ├── Solver calls get_dependencies() → LAZY MANIFEST FETCH               │
+│     ├── New dependencies discovered → new clauses added                      │
+│     ├── Propagation, conflict detection, backtracking                        │
+│     └── Repeat until solution or UNSAT                                       │
+│                                                                              │
+│  4. SOLUTION EXTRACTION                                                      │
+│     ├── Collect all selected solvables                                       │
+│     ├── For each: (package, version, rev, deps)                              │
+│     └── Build complete transitive closure                                    │
+│                                                                              │
+│  5. LOCK FILE GENERATION                                                     │
+│     ├── Convert solution to AtomDepV2 entries                                │
+│     ├── Include requires field for each dep                                  │
+│     ├── Mark direct deps with direct: true                                   │
+│     └── Write atom.lock v2 format                                            │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.2 Entry Point
+
+```rust
+/// Resolve all transitive dependencies for a manifest
+pub async fn resolve_transitive<S: LocalStorage>(
+    manifest: &ValidManifest,
+    resolved_sets: &ResolvedSets<'_, S>,
+    storage: &S,
+) -> Result<ResolutionResult, ResolutionError> {
+    // 1. Initialize resolver
+    let mut resolver = AtomResolver::new(resolved_sets, storage);
+    
+    // 2. Build initial problem from root manifest's direct deps
+    let problem = build_problem_from_manifest(&mut resolver, manifest)?;
+    
+    // 3. Create solver and solve
+    let solver = Solver::new(resolver);
+    let solution = solver.solve(problem).await?;
+    
+    // 4. Extract and return result
+    match solution {
+        Ok(solvables) => {
+            let result = extract_resolution_result(&resolver, &solvables, manifest)?;
+            Ok(result)
+        }
+        Err(unsolvable) => {
+            // TODO: Generate human-readable conflict explanation
+            Err(ResolutionError::Unsolvable(format_conflict(&resolver, unsolvable)))
+        }
+    }
+}
+
+fn build_problem_from_manifest<S: LocalStorage>(
+    resolver: &mut AtomResolver<'_, S>,
+    manifest: &ValidManifest,
+) -> Result<Problem, ResolutionError> {
+    let mut requirements = Vec::new();
+    
+    // Process each direct dependency
+    for (set_tag, deps) in manifest.as_ref().deps().from() {
+        let root = resolver.resolve_set_tag_to_root(set_tag)
+            .ok_or(ResolutionError::UnknownSet(set_tag.clone()))?;
+        
+        for (label, version_req) in deps {
+            let package = AtomId::from((root, label.clone()));
+            let name_id = resolver.pool.intern_package_name(package);
+            let vs = SemverVersionSet(version_req.clone());
+            let vs_id = resolver.pool.intern_version_set(name_id, vs);
+            
+            requirements.push(Requirement::Single(vs_id));
+        }
+    }
+    
+    // Include composer if it's an atom dependency
+    if let Compose::With(composer) = manifest.as_ref().composer() {
+        let root = resolver.resolve_set_tag_to_root(&composer.value.from)
+            .ok_or(ResolutionError::UnknownSet(composer.value.from.clone()))?;
+        
+        let package = AtomId::from((root, composer.key.clone()));
+        let name_id = resolver.pool.intern_package_name(package);
+        let version_req = composer.value.version().cloned().unwrap_or(VersionReq::STAR);
+        let vs = SemverVersionSet(version_req);
+        let vs_id = resolver.pool.intern_version_set(name_id, vs);
+        
+        requirements.push(Requirement::Single(vs_id));
+    }
+    
+    Ok(Problem {
+        requirements,
+        constraints: vec![],
+        soft_requirements: vec![],
+    })
+}
+```
+
+### 4.3 Result Extraction
+
+```rust
+/// Result of successful resolution
+pub struct ResolutionResult {
+    /// All resolved dependencies with their own requirements
+    pub deps: Vec<ResolvedDep>,
+    /// Set details for lock file
+    pub sets: BTreeMap<GitDigest, SetDetails>,
+}
+
+/// A single resolved dependency
+pub struct ResolvedDep {
+    pub label: Label,
+    pub version: Version,
+    pub set: GitDigest,
+    pub rev: GitDigest,
+    pub atom_id: AtomDigest,
+    /// Direct dependencies referenced by their AtomDigest
+    pub requires: Vec<AtomDigest>,
+    pub direct: bool,
+}
+
+fn extract_resolution_result<S: LocalStorage>(
+    resolver: &AtomResolver<'_, S>,
+    solvables: &[SolvableId],
+    root_manifest: &ValidManifest,
+) -> Result<ResolutionResult, ResolutionError> {
+    let direct_deps = collect_direct_deps(root_manifest, resolver)?;
+    
+    let mut deps = Vec::with_capacity(solvables.len());
+    
+    for &solvable_id in solvables {
+        let solvable = resolver.pool.resolve_solvable(solvable_id);
+        let package = resolver.pool.resolve_package_name(solvable.name);
+        
+        // Get dependencies for this solvable from cache
+        let cache_key = (package.clone(), solvable.record.version.clone());
+        let requires: Vec<AtomDigest> = resolver.manifest_cache
+            .get(&cache_key)
+            .map(|deps| {
+                deps.iter()
+                    .map(|d| d.target.compute_hash())
+                    .collect()
+            })
+            .unwrap_or_default();
+        
+        deps.push(ResolvedDep {
+            label: package.label().clone(),
+            version: solvable.record.version.clone(),
+            set: GitDigest::from(*package.root()),
+            rev: solvable.record.rev,
+            atom_id: solvable.record.atom_id,
+            requires,
+            direct: direct_deps.contains(&package),
+        });
+    }
+    
+    // Collect set details
+    let mut sets = BTreeMap::new();
+    for dep in &deps {
+        if let Some(details) = resolver.resolved_sets.details().get(&dep.set) {
+            sets.insert(dep.set, details.clone());
+        }
+    }
+    
+    Ok(ResolutionResult { deps, sets })
+}
+```
+
+---
+
+## Part 5: Lock File Migration
+
+### 5.1 Version Detection and Upgrade
+
+```rust
+impl Lockfile {
+    /// Detect lock file version and upgrade if necessary
+    pub fn from_str_with_upgrade(content: &str) -> Result<Self, LockError> {
+        // Try parsing as-is first
+        if let Ok(lock) = toml_edit::de::from_str::<Lockfile>(content) {
+            if lock.version >= 2 {
+                return Ok(lock);
+            }
+            // v1 lock detected - needs upgrade at resolution time
+            tracing::info!("detected v1 lock file, will upgrade to v2 on next resolve");
+            return Ok(lock);
+        }
+        
+        Err(LockError::ParseFailed)
+    }
+    
+    /// Check if lock file is v2 with full transitive closure
+    pub fn is_v2_complete(&self) -> bool {
+        self.version >= 2 && self.deps.as_ref().values().all(|dep| {
+            match dep {
+                Dep::Atom(atom) => atom.requires.is_some(),
+                _ => true,
+            }
+        })
+    }
+}
+```
+
+### 5.2 Writing Lock File v2
+
+```rust
+impl ResolutionResult {
+    /// Convert resolution result to lock file format
+    pub fn to_lockfile(&self, compose: Using) -> Lockfile {
+        let mut deps = DepMap::default();
+        
+        for resolved in &self.deps {
+            let id = AtomId::from((
+                Root::from(resolved.set),
+                resolved.label.clone(),
+            ));
+            
+            let atom_dep = AtomDepV2 {
+                label: resolved.label.clone(),
+                version: resolved.version.clone(),
+                set: resolved.set,
+                rev: resolved.rev,
+                mirror: None, // Mirrors looked up from sets table
+                id: resolved.atom_id,
+                requires: resolved.requires.clone(),
+                direct: resolved.direct,
+            };
+            
+            deps.as_mut().insert(
+                Either::Left(id),
+                Dep::Atom(atom_dep.into()),
+            );
+        }
+        
+        Lockfile {
+            version: 2,
+            sets: self.sets.clone(),
+            compose,
+            deps,
+        }
+    }
+}
+```
+
+---
+
+## Part 6: Integration with Existing Code
+
+### 6.1 ManifestWriter Changes
+
+Update `synchronize_atoms` to use full resolution:
+
+```rust
+impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
+    /// Synchronize lock file with manifest using full transitive resolution
+    pub(super) async fn synchronize_full(&mut self, manifest: &ValidManifest) -> Result<(), DocError> {
+        // Check if existing lock is v2 complete and still valid
+        if self.lock.is_v2_complete() && self.check_lock_validity(manifest)? {
+            tracing::debug!("existing v2 lock is valid, skipping re-resolution");
+            return Ok(());
+        }
+        
+        // Perform full transitive resolution
+        let result = resolve_transitive(
+            manifest,
+            &self.resolved,
+            self.resolved.ekala.storage,
+        ).await.map_err(|e| {
+            tracing::error!(error = %e, "transitive resolution failed");
+            DocError::ResolutionFailed
+        })?;
+        
+        // Update lock file with resolved deps
+        self.lock = result.to_lockfile(self.lock.compose.clone());
+        
+        // Synchronize direct (non-atom) dependencies
+        self.synchronize_direct(manifest).await?;
+        
+        Ok(())
+    }
+    
+    /// Check if existing lock file is still compatible with manifest requirements
+    fn check_lock_validity(&self, manifest: &ValidManifest) -> Result<bool, DocError> {
+        for (set_tag, deps) in manifest.as_ref().deps().from() {
+            let root = self.resolved.roots()
+                .get(&Either::Left(set_tag.clone()))
+                .ok_or(DocError::SetNotResolved)?;
+            
+            for (label, version_req) in deps {
+                let id = AtomId::from((*root, label.clone()));
+                
+                match self.lock.deps.as_ref().get(&Either::Left(id)) {
+                    Some(Dep::Atom(locked)) => {
+                        if !version_req.matches(locked.version()) {
+                            return Ok(false);
+                        }
+                    }
+                    _ => return Ok(false),
+                }
+            }
+        }
+        
+        Ok(true)
+    }
+}
+```
+
+### 6.2 CLI Command Updates
+
+Update `eka resolve` command:
+
+```rust
+/// Resolution command implementation
+pub async fn run_resolve(args: ResolveArgs) -> Result<(), Error> {
+    let storage = get_storage()?;
+    let manifest_path = args.manifest.unwrap_or_else(|| PathBuf::from("atom.toml"));
+    
+    // Open and validate manifest
+    let mut writer = ManifestWriter::open_and_resolve(
+        &storage,
+        &manifest_path,
+        args.fresh,
+    ).await?;
+    
+    // Perform full transitive resolution
+    let manifest = writer.manifest();
+    writer.synchronize_full(manifest).await?;
+    
+    // Write updated lock file
+    writer.write_atomic()?;
+    
+    tracing::info!(
+        deps_count = writer.lock().deps.as_ref().len(),
+        "resolution complete"
+    );
+    
+    Ok(())
+}
+```
+
+---
+
+## Part 7: Optimizations
+
+### 7.1 Speculative Prefetching
+
+When the solver picks a package, speculatively fetch manifests for top-k candidates in parallel:
+
+```rust
+impl<'a, S: LocalStorage> AtomResolver<'a, S> {
+    /// Speculatively prefetch manifests for likely candidates
+    async fn prefetch_candidates(&mut self, name: NameId, k: usize) {
+        let package: &AtomId<Root> = self.pool.resolve_package_name(name);
+        
+        if let Some(versions) = self.discovered_candidates.get(package) {
+            // Take top k versions (already sorted descending)
+            let to_prefetch: Vec<_> = versions.iter()
+                .take(k)
+                .filter(|v| !self.manifest_cache.contains_key(&(package.clone(), v.version.clone())))
+                .cloned()
+                .collect();
+            
+            if to_prefetch.is_empty() {
+                return;
+            }
+            
+            tracing::debug!(
+                package = %package,
+                count = to_prefetch.len(),
+                "prefetching candidate manifests"
+            );
+            
+            // Spawn parallel fetch tasks
+            let mut handles = Vec::new();
+            for v in to_prefetch {
+                let package = package.clone();
+                let version = v.version.clone();
+                let handle = tokio::spawn(async move {
+                    // Fetch logic here - use shared state carefully
+                    (package, version)
+                });
+                handles.push(handle);
+            }
+            
+            // Wait for all to complete (or timeout)
+            for handle in handles {
+                if let Ok((pkg, ver)) = tokio::time::timeout(
+                    std::time::Duration::from_secs(5),
+                    handle,
+                ).await.ok().and_then(|r| r.ok()) {
+                    // Mark as prefetched
+                }
+            }
+        }
+    }
+}
+```
+
+### 7.2 Lock File as Cache Hint
+
+Use existing lock file to hint `favored` and `locked` candidates:
+
+```rust
+fn apply_lock_hints(
+    resolver: &AtomResolver<'_, impl LocalStorage>,
+    lock: &Lockfile,
+    candidates: &mut Candidates,
+    package: &AtomId<Root>,
+) {
+    if lock.version < 2 {
+        return;
+    }
+    
+    // Find existing locked version for this package
+    for (key, dep) in lock.deps.as_ref() {
+        if let (Either::Left(id), Dep::Atom(atom)) = (key, dep) {
+            if id.root() == package.root()
+                && id.label() == package.label()
+            {
+                // Find the solvable for this version
+                if let Some(solvable_id) = candidates.candidates.iter().find(|&&sid| {
+                    let solvable = resolver.pool.resolve_solvable(sid);
+                    &solvable.record.version == atom.version()
+                }) {
+                    candidates.favored = Some(*solvable_id);
+                    candidates.locked = Some(*solvable_id);
+                }
+                break;
+            }
+        }
+    }
+}
+```
+
+### 7.3 Parallel Candidate Discovery
+
+Use tokio's JoinSet for parallel ref queries:
+
+```rust
+impl<'a, S: LocalStorage> AtomResolver<'a, S> {
+    /// Discover candidates for multiple packages in parallel
+    async fn discover_candidates_batch(
+        &mut self,
+        packages: Vec<AtomId<Root>>,
+    ) -> Result<(), BoxError> {
+        use tokio::task::JoinSet;
+        
+        let mut tasks = JoinSet::new();
+        
+        for package in packages {
+            if self.discovered_candidates.contains_key(&package) {
+                continue;
+            }
+            
+            let ref_pattern = format!(
+                "{}/*:{}/*",
+                format!("{}/{}", crate::ATOM_REFS.as_str(), package.label()),
+                format!("{}/{}", crate::ATOM_REFS.as_str(), package.label()),
+            );
+            let mirror_url = self.get_mirror_for_root(package.root())?;
+            
+            tasks.spawn(async move {
+                // Cheap ref query
+                let refs = tokio::task::spawn_blocking(move || {
+                    mirror_url.get_refs([ref_pattern.as_str()], None)
+                }).await??;
+                
+                Ok::<_, BoxError>((package, refs))
+            });
+        }
+        
+        while let Some(result) = tasks.join_next().await {
+            let (package, refs) = result??;
+            self.process_discovered_refs(package, refs)?;
+        }
+        
+        Ok(())
+    }
+}
+```
+
+---
+
+## Part 8: Error Handling and Diagnostics
+
+### 8.1 Resolution Error Types
+
+```rust
+#[derive(thiserror::Error, Debug)]
+pub enum ResolutionError {
+    #[error("no candidates found for package: {0}")]
+    NoCandidates(AtomId<Root>),
+    
+    #[error("no version satisfies requirements for {package}: {requirement}")]
+    NoMatchingVersion {
+        package: AtomId<Root>,
+        requirement: VersionReq,
+    },
+    
+    #[error("package set not found: {0}")]
+    UnknownSet(Tag),
+    
+    #[error("manifest fetch failed for {package}@{version}: {reason}")]
+    ManifestFetchFailed {
+        package: AtomId<Root>,
+        version: Version,
+        reason: String,
+    },
+    
+    #[error("resolution conflict:\n{explanation}")]
+    Unsolvable {
+        explanation: String,
+    },
+    
+    #[error(transparent)]
+    Storage(#[from] storage::git::Error),
+    
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+}
+```
+
+### 8.2 Conflict Explanation
+
+Resolvo provides built-in conflict reporting via the `Problem` type when solving fails.
+We leverage this directly rather than rolling our own:
+
+```rust
+use resolvo::UnsolvableOrCancelled;
+
+fn handle_resolution_failure<S: LocalStorage>(
+    resolver: &AtomResolver<'_, S>,
+    result: UnsolvableOrCancelled<Box<dyn std::any::Any>>,
+) -> ResolutionError {
+    match result {
+        UnsolvableOrCancelled::Unsolvable(problem) => {
+            // Resolvo's Problem type has display_user_friendly() for conflict explanation
+            // It walks the conflict graph and explains:
+            // - Which packages have incompatible requirements
+            // - What version constraints led to the conflict
+            // - The derivation chain showing how we got there
+            
+            // Use resolvo's built-in formatting
+            let explanation = problem.display_user_friendly(resolver).to_string();
+            
+            ResolutionError::Unsolvable { explanation }
+        }
+        UnsolvableOrCancelled::Cancelled(reason) => {
+            ResolutionError::Cancelled {
+                reason: format!("{:?}", reason),
+            }
+        }
+    }
+}
+```
+
+The `Problem::display_user_friendly()` method from resolvo generates clear explanations like:
+
+```
+The following packages are incompatible:
+├─ root requires foo ^2.0.0
+│  └─ foo 2.0.0 requires bar ^3.0.0
+│     └─ no version of bar satisfies ^3.0.0 AND ^2.0.0
+└─ root requires baz ^1.0.0
+   └─ baz 1.0.0 requires bar ^2.0.0
+```
+
+---
+
+## Part 9: Testing Strategy
+
+### 9.1 Testing Strategy
+
+**Principle**: Avoid MockResolver with different semantics. Instead:
+
+1. **Unit tests**: Test individual functions (ref parsing, version matching, constraint conversion)
+2. **Integration tests**: Use git fixtures that match real atom repository structure
+3. **Snapshot tests**: Compare resolution results against known-good outputs
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+    
+    /// Create a test git repository with atom refs
+    fn setup_test_repo() -> (TempDir, gix::Repository) {
+        let tmp = TempDir::new().unwrap();
+        let repo = gix::init_bare(&tmp).unwrap();
+        
+        // Create atom refs matching real structure:
+        // refs/eka/atoms/<label>/<version> -> commit
+        create_test_atom(&repo, "foo", "1.0.0", &[]);
+        create_test_atom(&repo, "foo", "1.1.0", &[("bar", "^1.0")]);
+        create_test_atom(&repo, "bar", "1.0.0", &[]);
+        create_test_atom(&repo, "bar", "2.0.0", &[]);
+        
+        (tmp, repo)
+    }
+    
+    fn create_test_atom(
+        repo: &gix::Repository,
+        label: &str,
+        version: &str,
+        deps: &[(&str, &str)],
+    ) {
+        // Create atom.toml content with deps
+        let manifest = format!(
+            r#"[package]
+label = "{}"
+version = "{}"
+[compose.as.nix]
+nix = "."
+[deps.from.test-set]
+{}
+"#,
+            label,
+            version,
+            deps.iter()
+                .map(|(l, v)| format!("{} = \"{}\"", l, v))
+                .collect::<Vec<_>>()
+                .join("\n")
+        );
+        
+        // Create tree with atom.toml
+        let blob = repo.write_blob(manifest.as_bytes()).unwrap();
+        let tree = repo.write_object(&gix::objs::Tree {
+            entries: vec![gix::objs::tree::Entry {
+                mode: gix::object::tree::EntryKind::Blob.into(),
+                oid: blob.detach(),
+                filename: "atom.toml".into(),
+            }],
+        }).unwrap();
+        
+        // Create commit
+        let commit = git::write_atom_commit_to_repo(
+            repo, tree.detach(), label, version, "test-root"
+        ).unwrap();
+        
+        // Create ref
+        repo.reference(
+            format!("refs/eka/atoms/{}/{}", label, version),
+            commit.tip(),
+            gix::refs::transaction::PreviousValue::Any,
+            "test setup",
+        ).unwrap();
+    }
+    
+    #[tokio::test]
+    async fn test_resolve_simple_chain() {
+        let (_tmp, repo) = setup_test_repo();
+        let storage = TestStorage::new(&repo);
+        
+        // Resolve foo ^1.0 which depends on bar ^1.0
+        let manifest = parse_manifest(r#"
+            [package]
+            label = "root"
+            version = "0.1.0"
+            [deps.from.test-set]
+            foo = "^1.0"
+        "#);
+        
+        let result = resolve_transitive(&manifest, &storage).await.unwrap();
+        
+        // Should select foo 1.1.0 (latest matching ^1.0) and bar 2.0.0 (latest matching ^1.0)
+        assert_eq!(result.get_version("foo"), Some(&Version::parse("1.1.0").unwrap()));
+        assert_eq!(result.get_version("bar"), Some(&Version::parse("2.0.0").unwrap()));
+    }
+    
+    #[tokio::test]
+    async fn test_conflict_produces_readable_error() {
+        let (_tmp, repo) = setup_test_repo();
+        // Add conflicting atoms
+        create_test_atom(&repo, "left", "1.0.0", &[("shared", "^1.0")]);
+        create_test_atom(&repo, "right", "1.0.0", &[("shared", "^2.0")]);
+        create_test_atom(&repo, "shared", "1.0.0", &[]);
+        create_test_atom(&repo, "shared", "2.0.0", &[]);
+        
+        let storage = TestStorage::new(&repo);
+        let manifest = parse_manifest(r#"
+            [package]
+            label = "root"
+            version = "0.1.0"
+            [deps.from.test-set]
+            left = "*"
+            right = "*"
+        "#);
+        
+        let result = resolve_transitive(&manifest, &storage).await;
+        assert!(result.is_err());
+        
+        // Check error message is useful
+        let err = result.unwrap_err();
+        assert!(err.to_string().contains("shared"));
+        assert!(err.to_string().contains("^1.0"));
+        assert!(err.to_string().contains("^2.0"));
+    }
+}
+```
+
+### 9.2 Integration Tests
+
+```rust
+#[test]
+fn test_lockfile_v2_roundtrip() {
+    let lock_content = r#"
+version = 2
+
+[sets."abc123"]
+tag = "test-atoms"
+mirrors = ["https://github.com/test/atoms"]
+
+[[deps]]
+type = "atom"
+label = "foo"
+version = "1.0.0"
+set = "abc123"
+rev = "def456"
+id = "789ghi"
+requires = [{ set = "abc123", label = "bar" }]
+direct = true
+
+[[deps]]
+type = "atom"
+label = "bar"
+version = "2.0.0"
+set = "abc123"
+rev = "jkl012"
+id = "mno345"
+requires = []
+"#;
+
+    let lock: Lockfile = toml_edit::de::from_str(lock_content).unwrap();
+    assert_eq!(lock.version, 2);
+    
+    let reserialized = toml_edit::ser::to_string_pretty(&lock).unwrap();
+    let reparsed: Lockfile = toml_edit::de::from_str(&reserialized).unwrap();
+    assert_eq!(lock, reparsed);
+}
+```
+
+---
+
+## Part 10: Implementation Phases
+
+### Phase 1: Data Structures (Week 1)
+
+- [ ] Add `Display` impl to `AtomId<Root>` for error messages
+- [ ] Implement `SemverVersionSet` wrapper for resolvo's `VersionSet` trait
+- [ ] Implement `AtomSolvableRecord` type for version metadata
+- [ ] Extend `AtomDep` with `requires: Vec<AtomDigest>` and `direct: bool` fields
+- [ ] Update `Lockfile` for v2 support (remove `mirror` from deps, add version field)
+- [ ] Add migration path for v1 → v2 lock files
+- [ ] Add unit tests for new types
+
+### Phase 2: AtomResolver Core (Week 2)
+
+- [ ] Implement `AtomResolver` struct with caches
+- [ ] Implement `DependencyProvider` trait methods
+- [ ] Implement `Interner` trait methods
+- [ ] Implement cheap ref queries for `get_candidates`
+- [ ] Implement lazy manifest fetch for `get_dependencies`
+- [ ] Add unit tests with mock transport
+
+### Phase 3: Resolution Entry Point (Week 3)
+
+- [ ] Implement `resolve_transitive` function
+- [ ] Implement `build_problem_from_manifest`
+- [ ] Implement `extract_resolution_result`
+- [ ] Implement conflict formatting
+- [ ] Update `ManifestWriter::synchronize` to use new resolver
+- [ ] Add integration tests
+
+### Phase 4: Optimization (Week 4)
+
+- [ ] Implement speculative prefetching
+- [ ] Implement lock file hints (`favored`, `locked`)
+- [ ] Implement parallel candidate discovery
+- [ ] Performance benchmarking
+- [ ] Document optimization strategies
+
+### Phase 5: CLI & Testing (Week 5)
+
+- [ ] Update `eka resolve` command
+- [ ] Update `eka lock` command
+- [ ] Add `--fresh` flag for force re-resolution
+- [ ] Add `--dry-run` flag for preview
+- [ ] Integration tests with git fixtures (not mocks)
+- [ ] Documentation updates
+
+### Phase 6: Nix Integration (Week 6)
+
+- [ ] Update evaluation manifest generation
+- [ ] Update nix-lock static code for v2 format
+- [ ] Test `eka plan` with new resolution
+- [ ] Verify store population from v2 lock
+- [ ] Migration guide documentation
+
+---
+
+## Part 11: Hypergraph Integration
+
+### 11.1 Lock File as Hypergraph
+
+The lock file v2 format naturally encodes a directed hypergraph:
+
+```
+Lock File Structure:
+┌─────────────────────────────────────────────────────────────────────┐
+│  deps[0]: { id: A, requires: [B, C] }  →  Hyperedge: A → {B, C}    │
+│  deps[1]: { id: B, requires: [D] }     →  Hyperedge: B → {D}       │
+│  deps[2]: { id: C, requires: [D, E] }  →  Hyperedge: C → {D, E}    │
+│  deps[3]: { id: D, requires: [] }      →  Leaf node: D             │
+│  deps[4]: { id: E, requires: [] }      →  Leaf node: E             │
+└─────────────────────────────────────────────────────────────────────┘
+
+Hypergraph Representation:
+       A
+      / \
+     B   C
+     |  / \
+     D    E
+```
+
+### 11.2 Using hyperdep for Analysis
+
+```rust
+use hyperdep::HyperGraph;
+
+impl LockfileV2 {
+    /// Convert lock file to hypergraph for analysis operations
+    pub fn to_hypergraph(&self) -> HyperGraph<AtomDigest, ()> {
+        let mut graph = HyperGraph::new();
+        
+        for (_key, dep) in self.deps.as_ref() {
+            if let Dep::Atom(atom) = dep {
+                // Add node
+                graph.add_node(atom.id);
+                
+                // Add hyperedge from this atom to its requirements
+                if !atom.requires.is_empty() {
+                    graph.add_edge(atom.id, atom.requires.clone(), ());
+                }
+            }
+        }
+        
+        graph
+    }
+    
+    /// Get topological order for evaluation (leaves first)
+    pub fn topo_order(&self) -> Vec<AtomDigest> {
+        self.to_hypergraph().topo_sort().unwrap_or_default()
+    }
+    
+    /// Find all atoms that depend on a given atom (reverse deps)
+    pub fn dependents_of(&self, atom: AtomDigest) -> Vec<AtomDigest> {
+        self.to_hypergraph().predecessors(&atom)
+    }
+    
+    /// Detect dependency cycles (should be empty for valid lock)
+    pub fn find_cycles(&self) -> Vec<Vec<AtomDigest>> {
+        self.to_hypergraph().find_cycles()
+    }
+}
+```
+
+### 11.3 Use Cases
+
+| Operation | hyperdep Method | Use Case |
+|-----------|-----------------|----------|
+| `topo_sort()` | Topological order | `eka plan` evaluation order |
+| `predecessors(node)` | Reverse dependencies | "What will break if I change X?" |
+| `successors(node)` | Forward dependencies | "What does X need?" |
+| `find_cycles()` | Cycle detection | Lock file validation |
+| `subgraph(nodes)` | Extract subset | Partial resolution |
+
+### 11.4 Note on Resolution vs. Hypergraph
+
+The hypergraph representation is for **post-resolution analysis**, not resolution itself:
+
+- **Resolution**: Handled by resolvo's SAT solver with its internal clause representation
+- **Analysis**: Once resolved, the lock file → hypergraph conversion enables graph queries
+
+This separation keeps concerns clean: resolvo handles the hard constraint satisfaction, hyperdep handles the graph traversal for downstream operations.
+
+---
+
+## Appendix A: Comparison with Cargo and Pixi
+
+| Aspect | Cargo | Pixi/Rattler | Eka (proposed) |
+|--------|-------|--------------|----------------|
+| Solver | Custom PubGrub | resolvo (CDCL) | resolvo (CDCL) |
+| Lock format | Cargo.lock | pixi.lock | atom.lock v2 |
+| Transitive deps | Stored with `requires` | Stored flat | Stored with `requires` |
+| Lazy loading | Version index | Full index | Cheap refs + lazy manifest |
+| Package identity | name@registry | name::channel | root::label |
+| Version constraint | semver | conda VersionSpec | semver |
+
+---
+
+## Appendix B: Glossary
+
+| Term | Definition |
+|------|------------|
+| **Atom** | Orphaned git commit containing a package's source tree |
+| **Root** | Repository identity (genesis commit hash) |
+| **Label** | Atom name within a repository |
+| **AtomId** | (Root, Label) pair uniquely identifying an atom package |
+| **Solvable** | Specific version of a package in resolvo's model |
+| **VersionSet** | Constraint on acceptable versions (e.g., `^1.0.0`) |
+| **CDCL** | Conflict-Driven Clause Learning (SAT algorithm) |
+| **Cheap ref query** | Git ls-remote that fetches ref metadata without objects |
+| **Manifest** | atom.toml file declaring dependencies |
+| **Lock** | atom.lock file pinning exact versions |
+
+---
+
+## References
+
+- [resolvo crate documentation](https://docs.rs/resolvo)
+- [ADR-0014: Resolution Architecture](./0014-resolution-architecture.md)
+- [Cargo resolver algorithm](https://doc.rust-lang.org/cargo/reference/resolver.html)
+- [PubGrub solver](https://nex3.medium.com/pubgrub-2fb6470504f)
+- [CDCL algorithm overview](https://en.wikipedia.org/wiki/Conflict-driven_clause_learning)
\ No newline at end of file
diff --git a/build/Cargo.nix b/build/Cargo.nix
index bd20900..a0c61a8 100644
--- a/build/Cargo.nix
+++ b/build/Cargo.nix
@@ -15213,6 +15213,10 @@ rec {
         ];
         src = lib.cleanSourceWith { filter = sourceFilter;  src = ../crates/nixec; };
         dependencies = [
+          {
+            name = "anyhow";
+            packageId = "anyhow";
+          }
           {
             name = "birdcage";
             packageId = "birdcage";
@@ -18761,9 +18765,9 @@ rec {
       };
       "rustls" = rec {
         crateName = "rustls";
-        version = "0.23.14";
+        version = "0.23.35";
         edition = "2021";
-        sha256 = "1a0b2sdvq69vqrz08wvjmlqafzh7pfgzhn9j0n107f9wd529jpa1";
+        sha256 = "13xxk2qqchibd7pr0laqq6pzayx9xm4rb45d8rz68kvxday58gsk";
         dependencies = [
           {
             name = "log";
@@ -18812,13 +18816,14 @@ rec {
         ];
         features = {
           "aws-lc-rs" = [ "aws_lc_rs" ];
-          "aws_lc_rs" = [ "dep:aws-lc-rs" "webpki/aws_lc_rs" ];
+          "aws_lc_rs" = [ "dep:aws-lc-rs" "webpki/aws-lc-rs" "aws-lc-rs/aws-lc-sys" "aws-lc-rs/prebuilt-nasm" ];
           "brotli" = [ "dep:brotli" "dep:brotli-decompressor" "std" ];
-          "default" = [ "aws_lc_rs" "logging" "std" "tls12" ];
-          "fips" = [ "aws_lc_rs" "aws-lc-rs?/fips" ];
+          "default" = [ "aws_lc_rs" "logging" "prefer-post-quantum" "std" "tls12" ];
+          "fips" = [ "aws_lc_rs" "aws-lc-rs?/fips" "webpki/aws-lc-rs-fips" ];
           "hashbrown" = [ "dep:hashbrown" ];
           "log" = [ "dep:log" ];
           "logging" = [ "log" ];
+          "prefer-post-quantum" = [ "aws_lc_rs" ];
           "read_buf" = [ "rustversion" "std" ];
           "ring" = [ "dep:ring" "webpki/ring" ];
           "rustversion" = [ "dep:rustversion" ];
@@ -18882,11 +18887,19 @@ rec {
       };
       "rustls-pki-types" = rec {
         crateName = "rustls-pki-types";
-        version = "1.9.0";
+        version = "1.13.0";
         edition = "2021";
-        sha256 = "0mcc901b4hm2ql2qwpf2gzqhqn6d7iag92hr872wjr8c6wsnws8f";
+        sha256 = "0yjzsnpv1sjbnfxbbmrnyimd23jip48nav6l9hr1rjd06vcjl64l";
         libName = "rustls_pki_types";
+        dependencies = [
+          {
+            name = "zeroize";
+            packageId = "zeroize";
+            optional = true;
+          }
+        ];
         features = {
+          "alloc" = [ "dep:zeroize" ];
           "default" = [ "alloc" ];
           "std" = [ "alloc" ];
           "web" = [ "web-time" ];
@@ -18896,9 +18909,9 @@ rec {
       };
       "rustls-webpki" = rec {
         crateName = "rustls-webpki";
-        version = "0.102.8";
+        version = "0.103.8";
         edition = "2021";
-        sha256 = "1sdy8ks86b7jpabpnb2px2s7f1sq8v0nqf6fnlvwzm4vfk41pjk4";
+        sha256 = "0lpymb84bi5d2pm017n39nbiaa5cd046hgz06ir29ql6a8pzmz9g";
         libName = "webpki";
         dependencies = [
           {
@@ -18920,8 +18933,10 @@ rec {
         ];
         features = {
           "alloc" = [ "ring?/alloc" "pki-types/alloc" ];
-          "aws_lc_rs" = [ "dep:aws-lc-rs" ];
-          "default" = [ "std" "ring" ];
+          "aws-lc-rs" = [ "dep:aws-lc-rs" "aws-lc-rs/aws-lc-sys" "aws-lc-rs/prebuilt-nasm" ];
+          "aws-lc-rs-fips" = [ "dep:aws-lc-rs" "aws-lc-rs/fips" ];
+          "aws-lc-rs-unstable" = [ "aws-lc-rs" "aws-lc-rs/unstable" ];
+          "default" = [ "std" ];
           "ring" = [ "dep:ring" ];
           "std" = [ "alloc" "pki-types/std" ];
         };
diff --git a/build/atom.lock b/build/atom.lock
index 69c70b5..daf8a64 100644
--- a/build/atom.lock
+++ b/build/atom.lock
@@ -15,9 +15,9 @@ mirrors = ["https://github.com/ekala-project/atom"]
 
 [locker]
 label = "nix-lock"
-version = "0.1.6"
+version = "0.3.0"
 set = "4abbd2644bc3585e9be95deb277ccf48f6ed26ac"
-rev = "e711aa1f48d877652dd2ba724d4af752be7b5371"
+rev = "ef40eecd6b0c6a5e8113937990b81d78418a0ff7"
 mirror = "https://github.com/ekala-project/eka"
 id = "r3rlam6bd31t9i04ggug7avs8vf8981q7a3b6gobemk1gfs50qm0"
 
@@ -44,4 +44,4 @@ id = "3ot6f917im3d5qhs1jdo2samkthlahg5qcr4ql5e2neomv2v6dt0"
 type = "nix+git"
 name = "eka"
 url = "https://github.com/ekala-project/eka.git"
-rev = "aa7399c89d6afae67e2eccd63e242ccd029dccd3"
+rev = "e699f085b1ce4c37d9706bd445223f5cb430c626"
diff --git a/build/default.nix b/build/default.nix
index ef41a21..f5ffcbb 100644
--- a/build/default.nix
+++ b/build/default.nix
@@ -3,19 +3,19 @@ let
   lock = builtins.fromTOML lockstr;
   inherit (lock) locker;
   ekaSrc = builtins.head (builtins.filter (x: x.name == "eka") lock.deps);
-  lockexpr =
-    import
-    <| builtins.fetchGit {
-      inherit (locker) rev;
-      name = locker.label;
-      url = locker.mirror;
-      ref = "refs/eka/atoms/${locker.label}/${locker.version}";
-    };
+  fetch = builtins.fetchGit {
+    inherit (locker) rev;
+    name = locker.label;
+    url = locker.mirror;
+    ref = "refs/eka/atoms/${locker.label}/${locker.version}";
+  };
+  lockexpr = import fetch;
 in
 lockexpr ./. lockstr {
   # FIXME: this is the only way to get the repository source into the atom for now
   # The long-term solution to this problem is specified in ../adrs/0010-electron-sources.md
   extraExtern.ext = rec {
+    inherit locker;
     cargo-lock = import (src + "/build/Cargo.nix");
     src =
       if builtins.pathExists ../. then
diff --git a/build/eka/mod.nix b/build/eka/mod.nix
index d8e5af0..67ab09e 100644
--- a/build/eka/mod.nix
+++ b/build/eka/mod.nix
@@ -20,9 +20,9 @@ in
           # split up the atom crate and use some of its functionality in the proc macro
           # to compute these from the local repository without having to contact the
           # network.
-          EKA_ROOT_COMMIT_HASH = "4abbd2644bc3585e9be95deb277ccf48f6ed26ac";
-          EKA_ORIGIN_URL = "https://github.com/ekala-project/eka";
-          EKA_LOCK_REV = "e711aa1f48d877652dd2ba724d4af752be7b5371";
+          EKA_ROOT_COMMIT_HASH = ext.locker.set;
+          EKA_ORIGIN_URL = ext.locker.mirror;
+          EKA_LOCK_REV = ext.locker.rev;
         };
       }
       // builtins.listToAttrs (
diff --git a/crates/atom/Cargo.toml b/crates/atom/Cargo.toml
index 03a1cf4..9c45e38 100644
--- a/crates/atom/Cargo.toml
+++ b/crates/atom/Cargo.toml
@@ -8,8 +8,10 @@ addr       = "^0.15"
 base32     = "^0.5"
 blake3     = "^1.8"
 bstr       = "^1"
+ignore     = "^0.4"
 nom        = "^7"
 path-clean = "^1"
+resolvo    = "0.10"
 
 bimap.workspace                 = true
 either.workspace                = true
@@ -29,6 +31,7 @@ unicode-ident.workspace         = true
 unicode-normalization.workspace = true
 url.workspace                   = true
 
+base58 = "0.2.0"
 config = { path = "../config" }
 eka-root-macro = { path = "../eka-root-macro" }
 gix = { workspace = true, default-features = false, features = ["serde"] }
diff --git a/crates/atom/src/id/mod.rs b/crates/atom/src/id/mod.rs
index ecd91e6..dc76fd1 100644
--- a/crates/atom/src/id/mod.rs
+++ b/crates/atom/src/id/mod.rs
@@ -75,7 +75,6 @@ use std::ffi::OsStr;
 use std::fmt::{self, Display};
 use std::ops::Deref;
 use std::str::FromStr;
-use std::sync::LazyLock;
 
 use serde::{Deserialize, Serialize, Serializer};
 use thiserror::Error;
@@ -83,7 +82,6 @@ use thiserror::Error;
 use crate::storage::git::Root;
 
 const ID_MAX: usize = 128;
-pub(crate) static LOCK_LABEL: LazyLock<Label> = LazyLock::new(|| Label(crate::LOCK_LABEL.into()));
 
 //================================================================================================
 // Types
diff --git a/crates/atom/src/lib.rs b/crates/atom/src/lib.rs
index 168ab35..8994864 100644
--- a/crates/atom/src/lib.rs
+++ b/crates/atom/src/lib.rs
@@ -76,6 +76,9 @@ pub mod package;
 pub mod storage;
 pub mod uri;
 
+#[cfg(test)]
+pub mod test;
+
 // Sets compile time constants
 eka_root_macro::eka_origin_info!();
 
diff --git a/crates/atom/src/package/metadata/lock/direct/mod.rs b/crates/atom/src/package/metadata/lock/direct/mod.rs
index baf6e1e..e0cfbf5 100644
--- a/crates/atom/src/package/metadata/lock/direct/mod.rs
+++ b/crates/atom/src/package/metadata/lock/direct/mod.rs
@@ -1,4 +1,4 @@
-use id::Name;
+use id::{AtomDigest, Name};
 use nix_compat::nixhash::NixHash;
 use package::metadata::GitDigest;
 use package::metadata::manifest::direct::{NixFetch, NixReq};
@@ -27,6 +27,9 @@ pub struct BuildSrc {
     pub url: Url,
     /// The hash for verification.
     hash: WrappedNixHash,
+    /// The atom that owns this dep (None if root's direct dep).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub owner: Option<AtomDigest>,
 }
 
 /// Represents a direct pin to an external source, such as a URL or tarball.
@@ -42,6 +45,9 @@ pub struct NixDep {
     url: Url,
     /// The hash for integrity verification (e.g., sha256).
     hash: WrappedNixHash,
+    /// The atom that owns this dep (None if root's direct dep).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub owner: Option<AtomDigest>,
 }
 
 /// Represents a pinned Git repository with a specific revision.
@@ -57,10 +63,13 @@ pub struct NixGitDep {
     #[serde(with = "serde_gix_url")]
     pub url: gix::Url,
     /// The version which was resolved (if requested).
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub version: Option<Version>,
     /// The resolved revision (commit hash).
     pub rev: GitDigest,
+    /// The atom that owns this dep (None if root's direct dep).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub owner: Option<AtomDigest>,
 }
 
 /// Represents a pinned tarball or archive source.
@@ -76,6 +85,9 @@ pub struct NixTarDep {
     pub url: Url,
     /// The hash of the tarball.
     hash: WrappedNixHash,
+    /// The atom that owns this dep (None if root's direct dep).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub owner: Option<AtomDigest>,
 }
 
 /// A wrapper around `NixHash` to provide custom serialization behavior for TOML.
@@ -94,7 +106,12 @@ pub(in crate::package) enum NixUrls<'a> {
 
 impl BuildSrc {
     pub(in crate::package) fn new(name: Name, url: Url, hash: WrappedNixHash) -> Self {
-        Self { name, url, hash }
+        Self {
+            name,
+            url,
+            hash,
+            owner: None,
+        }
     }
 
     pub(crate) fn name(&self) -> &Name {
@@ -119,7 +136,12 @@ impl NixFetch {
 
 impl NixDep {
     pub(crate) fn new(name: Name, url: Url, hash: WrappedNixHash) -> Self {
-        Self { name, url, hash }
+        Self {
+            name,
+            url,
+            hash,
+            owner: None,
+        }
     }
 
     pub(crate) fn name(&self) -> &Name {
@@ -143,7 +165,12 @@ impl NixGitDep {
 
 impl NixTarDep {
     pub(in crate::package) fn new(name: Name, url: Url, hash: WrappedNixHash) -> Self {
-        Self { name, url, hash }
+        Self {
+            name,
+            url,
+            hash,
+            owner: None,
+        }
     }
 
     pub(crate) fn name(&self) -> &Name {
diff --git a/crates/atom/src/package/metadata/lock/mod.rs b/crates/atom/src/package/metadata/lock/mod.rs
index ee81962..d52d372 100644
--- a/crates/atom/src/package/metadata/lock/mod.rs
+++ b/crates/atom/src/package/metadata/lock/mod.rs
@@ -73,7 +73,6 @@
 use std::collections::{BTreeMap, BTreeSet};
 use std::ops::Deref;
 use std::path::PathBuf;
-use std::sync::LazyLock;
 
 use direct::{BuildSrc, NixDep, NixGitDep, NixTarDep};
 use gix::ObjectId;
@@ -85,36 +84,12 @@ use semver::Version;
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 use storage::UnpackedRef;
 use storage::git::Root;
-use uri::serde_gix_url;
 
 use super::{GitDigest, manifest};
-use crate::{AtomId, BoxError, id, package, storage, uri};
+use crate::{AtomId, BoxError, id, package, storage};
 
 pub(in crate::package) mod direct;
 
-static LOCK_ATOM: LazyLock<AtomDep> = LazyLock::new(|| {
-    let label: Label = id::LOCK_LABEL.to_owned();
-    let id = AtomId::from((storage::git::LOCK_ROOT, label));
-    let hash = id.compute_hash();
-    let version = Version {
-        major: crate::LOCK_MAJOR,
-        minor: crate::LOCK_MINOR,
-        patch: crate::LOCK_PATCH,
-        pre: Default::default(),
-        build: Default::default(),
-    };
-
-    let mirror = gix::url::parse(crate::EKA_ORIGIN_URL.into()).ok();
-    AtomDep {
-        label: id.label().to_owned(),
-        version,
-        set: GitDigest::Sha1(crate::EKA_ROOT_COMMIT_HASH),
-        rev: Some(GitDigest::Sha1(crate::LOCK_REV)),
-        mirror,
-        id: hash,
-    }
-});
-
 //================================================================================================
 // Types
 //================================================================================================
@@ -125,28 +100,30 @@ static LOCK_ATOM: LazyLock<AtomDep> = LazyLock::new(|| {
 /// fetch a specific version of an atom from a Git repository.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, PartialOrd, Ord)]
 #[serde(deny_unknown_fields)]
-pub(crate) struct AtomDep {
+pub struct AtomDep {
     /// The unique identifier of the atom.
     label: Label,
     /// The semantic version of the atom.
     version: Version,
     /// The location of the atom, whether local or remote.
     set: GitDigest,
-    /// The resolved Git revision (commit hash) for verification. If it is `None`, it applies a
-    /// local only dependency which must be looked up by path. Atom's without revsions for all
-    /// other atoms in their lock cannot themsevles be published.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    rev: Option<GitDigest>,
-    /// The the primary url the atom was first resolved from. Needed for legacy tools which can't
-    /// resolve mirrors (e.g. nix).
-    #[serde(
-        default,
-        with = "serde_gix_url::maybe",
-        skip_serializing_if = "Option::is_none"
-    )]
-    mirror: Option<gix::Url>,
+    /// The resolved or calculated (if local) Git revision (commit hash) for verification.
+    rev: GitDigest,
     /// The cryptographic identity of the atom.
     id: AtomDigest,
+    /// Direct dependencies of this atom, referenced by their AtomDigest.
+    /// This enables reconstruction of the dependency graph from the lock file.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    requires: Vec<AtomDigest>,
+    /// Whether this is a direct dependency (from manifest) or transitive.
+    /// Direct dependencies are those explicitly listed in the root atom.toml.
+    #[serde(default, skip_serializing_if = "is_true")]
+    direct: bool,
+}
+
+/// Helper for serde skip_serializing_if - skips when true (direct deps are default)
+fn is_true(b: &bool) -> bool {
+    *b
 }
 
 /// Enum representing the different types of locked dependencies, serialized as tagged TOML tables.
@@ -212,17 +189,17 @@ pub(in crate::package) enum Using {
     /// an atom containing a nix expression that is just evaluated by calling `import`
     #[serde(rename = "nix")]
     NixTrivial { entry: PathBuf },
-    /// an atom containing a nix expression that is evaluated with the contained `NixComposer` atom
-    #[serde(rename = "atom")]
-    Atom {
-        #[serde(flatten)]
-        atom: AtomDep,
-        entry: PathBuf,
-    },
     /// an atom that contains only static configuration for use at evaluation time to other atoms
     #[serde(rename = "static")]
     #[default]
     Config,
+    /// an atom containing a nix expression that is evaluated with the contained `NixComposer` atom
+    #[serde(untagged)]
+    Atom {
+        at: Version,
+        entry: PathBuf,
+        r#use: AtomDigest,
+    },
 }
 
 /// The root structure for the lockfile, containing resolved dependencies and sources.
@@ -233,18 +210,17 @@ pub(in crate::package) enum Using {
 /// across different environments.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq)]
 #[serde(deny_unknown_fields)]
+#[derive(Default)]
 pub struct Lockfile {
     /// The version of the lockfile schema.
     ///
     /// This field allows for future evolution of the lockfile format while
     /// maintaining backward compatibility.
-    pub version: u8,
+    pub version: u16,
 
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub(crate) sets: BTreeMap<GitDigest, SetDetails>,
 
-    locker: AtomDep,
-
     pub(in crate::package) compose: Using,
     /// The list of locked dependencies (absent or empty if none).
     ///
@@ -273,29 +249,50 @@ impl Using {
 }
 
 impl AtomDep {
+    /// Creates a new locked atom dependency with full resolution information.
     pub(in crate::package) fn new(
         label: Label,
         version: Version,
         set: GitDigest,
-        rev: Option<GitDigest>,
-        mirror: Option<gix::Url>,
+        rev: GitDigest,
         id: AtomDigest,
+        requires: Vec<AtomDigest>,
+        direct: bool,
     ) -> Self {
         Self {
             label,
             version,
             set,
             rev,
-            mirror,
             id,
+            requires,
+            direct,
         }
     }
 
-    pub(crate) fn version(&self) -> &Version {
+    /// Creates a new direct dependency (for backwards compatibility).
+    pub(in crate::package) fn new_direct(
+        label: Label,
+        version: Version,
+        set: GitDigest,
+        rev: GitDigest,
+        id: AtomDigest,
+    ) -> Self {
+        Self::new(label, version, set, rev, id, Vec::new(), true)
+    }
+
+    /// retrieve the version this atom is locked to
+    pub fn version(&self) -> &Version {
         &self.version
     }
 
-    pub(crate) fn label(&self) -> &Label {
+    /// retrieve the atom id digest
+    pub fn id(&self) -> AtomDigest {
+        self.id
+    }
+
+    /// retrieve the label for this atom
+    pub fn label(&self) -> &Label {
         &self.label
     }
 
@@ -303,9 +300,19 @@ impl AtomDep {
         self.set
     }
 
-    pub(crate) fn rev(&self) -> Option<GitDigest> {
+    pub fn rev(&self) -> GitDigest {
         self.rev
     }
+
+    /// Returns the direct dependencies of this atom.
+    pub fn requires(&self) -> &[AtomDigest] {
+        &self.requires
+    }
+
+    /// Returns true if this is a direct dependency (explicitly in manifest).
+    pub fn is_direct(&self) -> bool {
+        self.direct
+    }
 }
 
 impl std::fmt::Display for Dep {
@@ -392,31 +399,21 @@ impl<R, T: Ord> AsRef<BTreeMap<DepKey<R>, T>> for DepMap<R, T> {
     }
 }
 
-impl From<ResolvedAtom<Option<ObjectId>, Root>> for AtomDep {
-    fn from(atom: ResolvedAtom<Option<ObjectId>, Root>) -> Self {
+impl From<ResolvedAtom<ObjectId, Root>> for AtomDep {
+    fn from(atom: ResolvedAtom<ObjectId, Root>) -> Self {
         let UnpackedRef { id, version, rev } = atom.unpack();
         AtomDep {
             label: id.label().to_owned(),
             version: version.to_owned(),
-            rev: rev.map(GitDigest::from),
+            rev: (*rev).into(),
             set: GitDigest::from(id.root().deref().to_owned()),
             id: id.compute_hash(),
-            mirror: atom.remotes().first().map(ToOwned::to_owned),
+            // From<ResolvedAtom> is used for direct deps; requires filled later by resolver
+            requires: Vec::new(),
+            direct: true,
         }
     }
 }
-impl From<ResolvedAtom<ObjectId, Root>> for AtomDep {
-    fn from(value: ResolvedAtom<ObjectId, Root>) -> Self {
-        let ResolvedAtom {
-            unpacked: UnpackedRef { id, version, rev },
-            remotes,
-        } = value;
-        AtomDep::from(ResolvedAtom::new(
-            UnpackedRef::new(id, version, Some(rev)),
-            remotes,
-        ))
-    }
-}
 
 impl Deref for AtomDep {
     type Target = Label;
@@ -468,18 +465,6 @@ impl std::fmt::Display for GitDigest {
     }
 }
 
-impl Default for Lockfile {
-    fn default() -> Self {
-        Self {
-            version: 1,
-            locker: LOCK_ATOM.to_owned(),
-            sets: Default::default(),
-            compose: Using::default(),
-            deps: Default::default(),
-        }
-    }
-}
-
 //================================================================================================
 // Tests
 //================================================================================================
diff --git a/crates/atom/src/package/metadata/lock/test.rs b/crates/atom/src/package/metadata/lock/test.rs
index f184028..bbe35c7 100644
--- a/crates/atom/src/package/metadata/lock/test.rs
+++ b/crates/atom/src/package/metadata/lock/test.rs
@@ -15,9 +15,8 @@ const TOML_LOCK: &str = include_str!("test/atom.lock");
 #[test]
 fn parse_lock() -> anyhow::Result<()> {
     // Test that a valid lockfile can be parsed successfully.
-    let lock: Lockfile = toml_edit::de::from_str(TOML_LOCK)?;
+    let _lock: Lockfile = toml_edit::de::from_str(TOML_LOCK)?;
 
-    assert_eq!(lock.locker, super::LOCK_ATOM.to_owned());
     // Test that a lockfile with an invalid dependency is rejected.
     let invalid_lock_str = r#"
 version = 1
diff --git a/crates/atom/src/package/metadata/lock/test/atom.lock b/crates/atom/src/package/metadata/lock/test/atom.lock
index 0cb8320..d456ed8 100644
--- a/crates/atom/src/package/metadata/lock/test/atom.lock
+++ b/crates/atom/src/package/metadata/lock/test/atom.lock
@@ -1,15 +1,8 @@
 version = 1
 
-[locker]
-label = "nix-lock"
-version = "0.1.6"
-set = "4abbd2644bc3585e9be95deb277ccf48f6ed26ac"
-rev = "e711aa1f48d877652dd2ba724d4af752be7b5371"
-mirror = "https://github.com/ekala-project/eka"
-id = "r3rlam6bd31t9i04ggug7avs8vf8981q7a3b6gobemk1gfs50qm0"
-
 [compose]
-use = "nix"
+with = "nei65m8kevs1l37b2eefu440k725fsj6pqj3mq3ob20sfhb64ud0"
+at = "1.0.1"
 entry = "."
 
 [sets]
diff --git a/crates/atom/src/package/metadata/manifest/mod.rs b/crates/atom/src/package/metadata/manifest/mod.rs
index 016fc9c..4d237e5 100644
--- a/crates/atom/src/package/metadata/manifest/mod.rs
+++ b/crates/atom/src/package/metadata/manifest/mod.rs
@@ -72,6 +72,7 @@ use std::str::FromStr;
 
 use config::ComposerSettings;
 use direct::DirectDeps;
+use either::Either;
 use gix::Url;
 use id::{Tag, VerifiedName};
 use lock::{AtomDep, Lockfile, SetDetails};
@@ -104,7 +105,7 @@ pub enum ComposeError {
 
 /// trivial composers are specified with the `ComposeKind::As` variant
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq)]
-pub(super) enum TrivialAtom {
+pub(in crate::package) enum TrivialAtom {
     /// just calls import on the contained nix expression at the provided path inside the atom,
     /// relative its root
     #[serde(rename = "nix")]
@@ -115,14 +116,14 @@ pub(super) enum TrivialAtom {
 }
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq)]
-pub(super) enum StaticAtom {
+pub(in crate::package) enum StaticAtom {
     /// Atom is provided at evaluation tme to consumers as shared configuration
     #[serde(rename = "config")]
     Config,
 }
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq)]
-pub(super) enum Compose {
+pub(in crate::package) enum Compose {
     #[serde(rename = "with")]
     With(AtomComposer),
     #[serde(rename = "as")]
@@ -188,7 +189,7 @@ type AtomFrom = HashMap<Tag, HashMap<Label, VersionReq>>;
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq)]
 #[serde(deny_unknown_fields)]
-pub(super) struct ComposerSpec {
+pub(in crate::package) struct ComposerSpec {
     from: Tag,
     #[serde(skip_serializing_if = "Option::is_none")]
     version: Option<VersionReq>,
@@ -368,7 +369,7 @@ pub struct ManifestWriter<'a, S: LocalStorage> {
     pub(in crate::package) resolved: ResolvedSets<'a, S>,
 }
 
-pub(in crate::package) struct AtomWriter {
+pub(crate) struct AtomWriter {
     set_tag: Tag,
     atom_req: AtomReq,
     mirror: SetMirror,
@@ -382,7 +383,7 @@ pub(in crate::package) struct AtomWriter {
 ///
 /// This trait now works with [`ValidManifest`] to ensure that all dependency
 /// modifications maintain manifest consistency and validation.
-pub(in crate::package) trait WriteDeps<T: Serialize, K: VerifiedName> {
+pub(crate) trait WriteDeps<T: Serialize, K: VerifiedName> {
     /// The error type returned by the methods.
     type Error;
 
@@ -505,7 +506,10 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
         Ok(writer)
     }
 
-    pub(super) fn set_lock_compose(&mut self, manifest: &ValidManifest) -> Result<(), DocError> {
+    pub(in crate::package) fn set_lock_compose(
+        &mut self,
+        manifest: &ValidManifest,
+    ) -> Result<(), DocError> {
         use lock::Using;
         let compose = match &manifest.as_ref().compose {
             Compose::With(composer) => {
@@ -522,12 +526,19 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
                         .as_ref()
                         .unwrap_or(&VersionReq::STAR)
                         .to_owned(),
-                    id,
+                    id.clone(),
                     composer.value.from.to_owned(),
                 )?;
+                let r#use = dep.id();
+                let at = dep.version().to_owned();
+                self.lock
+                    .deps
+                    .as_mut()
+                    .insert(Either::Left(id), lock::Dep::Atom(dep));
                 Using::Atom {
-                    atom: dep,
                     entry: composer.value.entry.to_owned(),
+                    r#use,
+                    at,
                 }
             },
             Compose::As(TrivialAtom::Nix(path)) => Using::NixTrivial {
@@ -544,7 +555,6 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
     /// to ensure that we are never operating on a stale manifest.
     async fn reconcile(&mut self, manifest: &ValidManifest) -> Result<(), DocError> {
         self.set_lock_sets();
-        self.set_lock_compose(manifest)?;
         self.sanitize(manifest);
         self.synchronize(manifest).await?;
         Ok(())
@@ -698,7 +708,7 @@ impl WriteDeps<ValidManifest, Label> for AtomWriter {
 }
 
 impl AtomWriter {
-    pub(in crate::package) fn new(set_tag: Tag, atom_req: AtomReq, mirror: SetMirror) -> Self {
+    pub(crate) fn new(set_tag: Tag, atom_req: AtomReq, mirror: SetMirror) -> Self {
         Self {
             set_tag,
             atom_req,
diff --git a/crates/atom/src/package/metadata/mod.rs b/crates/atom/src/package/metadata/mod.rs
index b6f4245..79062be 100644
--- a/crates/atom/src/package/metadata/mod.rs
+++ b/crates/atom/src/package/metadata/mod.rs
@@ -22,7 +22,7 @@ use std::collections::{BTreeMap, BTreeSet, HashMap};
 use std::marker::PhantomData;
 use std::path::{Path, PathBuf};
 
-use bimap::{BiBTreeMap, Overwritten};
+use bimap::BiBTreeMap;
 use id::{Label, Tag};
 use manifest::{AtomSet, ComposeError, Manifest, SetMirror};
 use semver::Version;
@@ -91,7 +91,7 @@ pub struct Meta {
 
 /// A newtype wrapper to tie a `DocumentMut` to a specific serializable type `T`.
 #[derive(Debug)]
-pub(super) struct TypedDocument<T> {
+pub(crate) struct TypedDocument<T> {
     /// The underlying `toml_edit` document.
     inner: DocumentMut,
     _marker: PhantomData<T>,
@@ -171,17 +171,48 @@ pub enum DocError {
     SetError(#[from] sets::Error),
 }
 
-/// The section of the manifest describing the Ekala set of atoms.
-#[derive(Serialize, Deserialize, Debug, PartialEq, Eq)]
+/// Internal type for raw deserialization of the set section.
+/// Contains unvalidated paths - labels not yet resolved.
+#[derive(Serialize, Deserialize, Debug)]
 #[serde(deny_unknown_fields)]
-pub struct EkalaSet {
+pub(crate) struct RawEkalaSet {
     #[serde(default)]
+    packages: Vec<PathBuf>,
+}
+
+impl RawEkalaSet {
+    /// Returns the raw package paths.
+    pub(crate) fn packages(&self) -> &[PathBuf] {
+        &self.packages
+    }
+}
+
+/// Internal type for raw deserialization of ekala.toml.
+/// MUST be validated before use via `EkalaManifest::open_*` constructors.
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct RawEkalaManifest {
+    pub(crate) set: RawEkalaSet,
+    metadata: Option<MetaData>,
+}
+
+/// The section of the manifest describing the Ekala set of atoms.
+///
+/// Contains a validated `AtomMap` with unique labels.
+/// This type can only be constructed via validated constructors,
+/// ensuring the label uniqueness invariant is maintained.
+#[derive(Serialize, Debug, PartialEq, Eq)]
+pub struct EkalaSet {
     pub(in crate::package) packages: AtomMap,
 }
 
 /// The entrypoint for an ekala manifest describing a set of atoms.
-#[derive(Serialize, Deserialize, Debug, PartialEq, Eq)]
-#[serde(deny_unknown_fields)]
+///
+/// This type can ONLY be constructed via validated constructors like
+/// `open_filesystem()` or `from_git_tree()`, ensuring that label
+/// uniqueness is validated. This makes invalid state literally
+/// unrepresentable at the type level.
+#[derive(Serialize, Debug, PartialEq, Eq)]
 pub struct EkalaManifest {
     pub(super) set: EkalaSet,
     metadata: Option<MetaData>,
@@ -196,8 +227,10 @@ struct MetaData {
 #[derive(Debug)]
 pub struct EkalaManager<'a, S: LocalStorage> {
     path: PathBuf,
-    doc: TypedDocument<EkalaManifest>,
+    /// The raw document for TOML editing
+    doc: TypedDocument<RawEkalaManifest>,
     pub(super) storage: &'a S,
+    /// The validated manifest with unique labels
     pub(super) manifest: EkalaManifest,
 }
 
@@ -217,7 +250,7 @@ pub enum GitDigest {
 }
 
 #[derive(Debug, PartialEq, Eq, Clone)]
-struct Singleton<K, V> {
+pub(super) struct Singleton<K, V> {
     key: K,
     value: V,
 }
@@ -314,6 +347,11 @@ impl Atom {
         self.label
     }
 
+    /// take both the label and version discarding self
+    pub fn take(self) -> (Label, Version) {
+        (self.label, self.version)
+    }
+
     /// return a reference to the atom's version
     pub fn version(&self) -> &Version {
         &self.version
@@ -380,143 +418,8 @@ impl AsMut<BiBTreeMap<Label, PathBuf>> for AtomMap {
     }
 }
 
-/// # AtomMap Deserialization: Enforcing Repository Path Invariants
-///
-/// This implementation provides a unique deserialization strategy for `AtomMap` that
-/// conditionally enforces path normalization based on repository availability. This
-/// behavior is crucial for maintaining the integrity of atom paths within the Ekala
-/// ecosystem.
-///
-/// ## Purpose
-///
-/// The primary goal is to prevent atom paths from escaping the repository boundary.
-/// Since `AtomMap` is constructed from the actual on-disk manifest during deserialization,
-/// this provides an opportunity to validate and normalize paths early in the process,
-/// failing fast if any path would violate the repository containment invariant.
-///
-/// ## Behavior
-///
-/// - **When inside a repository**: Paths are normalized using the repository's `normalize()`
-///   method, which ensures all paths are relative to the repository root and contained within the
-///   repository boundaries. If normalization fails (indicating a path outside the repository),
-///   deserialization fails immediately.
-///
-/// - **When outside a repository**: Paths are left as-is, allowing normal operation in
-///   non-repository contexts (e.g., testing, standalone usage).
-///
-/// ## Implementation Details
-///
-/// The implementation uses a global static reference to a lazily initialized repository
-/// instance (`git::repo()`). This ensures:
-/// - Efficient access: The repository is only discovered once per process
-/// - Conditional behavior: Normalization only occurs when a repository is available
-/// - Thread safety: Uses `OnceLock` for safe static initialization
-///
-/// ## Why This Matters
-///
-/// Atom paths must never escape the repository because they represent internal
-/// references that are meaningless outside the repository context. By enforcing
-/// this invariant during deserialization, we prevent invalid states that could
-/// lead to data corruption, security issues, or inconsistent behavior.
-///
-/// ## Error Handling
-///
-/// If path normalization fails when a repository is present, deserialization
-/// returns a custom error, preventing the creation of an invalid `AtomMap` instance.
-/// This early failure ensures problems are caught during manifest loading rather
-/// than later during atom resolution.
-///
-/// ## Additional Invariants
-///
-/// Beyond path containment, this implementation also enforces that no two atoms
-/// share the same label. Since the map is keyed by `Label`, duplicate labels would
-/// overwrite entries, losing atom identity. The implementation detects and rejects
-/// such conflicts during deserialization, ensuring each atom maintains its distinct
-/// identity.
-impl<'de> Deserialize<'de> for AtomMap {
-    /// Deserializes a list of paths into an `AtomMap`, enforcing repository path invariants.
-    ///
-    /// This function transforms a serialized list of paths into a map keyed by atom labels,
-    /// acquired directly from each atom's manifest. This approach enables canonical addressing
-    /// and efficient lookups while enforcing crucial invariants: path containment within the
-    /// repository and uniqueness of atom labels.
-    ///
-    /// The deserialization process:
-    /// 1. Deserializes the input as a `Vec<PathBuf>`
-    /// 2. For each path, normalizes it relative to the repository root (when in a repo)
-    /// 3. Reads the atom manifest to extract the canonical label
-    /// 4. Ensures no duplicate labels exist
-    /// 5. Constructs the final `BTreeMap<Label, PathBuf>`
-    ///
-    /// # Errors
-    ///
-    /// Returns an error if:
-    /// - Path normalization fails (paths outside repository when in repo context)
-    /// - Atom manifest cannot be read or parsed
-    /// - Multiple atoms share the same label
-    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
-    where
-        D: serde::Deserializer<'de>,
-    {
-        use path_clean::PathClean;
-        use serde::de;
-        use storage::{NormalizeStorePath, git};
-        let repo = git::repo().ok().flatten().map(|r| r.to_thread_local());
-        let entries: Vec<PathBuf> = Vec::deserialize(deserializer)?;
-        let mut map = BiBTreeMap::new();
-
-        let rel_to_root = repo
-            .as_ref()
-            .ok_or(storage::git::Error::NoWorkDir)
-            .and_then(|r| r.rel_from_root(r.current_dir()));
-        for path in entries {
-            let normalized = if let Some(repo) = &repo {
-                let rel_to_root = rel_to_root.as_ref().map_err(de::Error::custom)?;
-                let rel_path = rel_to_root.join(&path);
-                let cwd = repo
-                    .normalize(repo.current_dir())
-                    .map_err(de::Error::custom)?;
-                let normal = repo.normalize(&rel_path).map_err(de::Error::custom)?;
-                pathdiff::diff_paths(&normal, cwd)
-                    .unwrap_or(rel_path)
-                    .clean()
-            } else {
-                path.clean()
-            };
-            let label = if let Ok(l) =
-                Manifest::get_atom_label(normalized.join(crate::ATOM_MANIFEST_NAME.as_str()))
-                    .inspect_err(|e| {
-                        tracing::warn!(
-                            error = %e,
-                            path = %normalized.display(),
-                            suggestion = "you likely want to remove it from the set, or perhaps recreate it",
-                            "atom no longer exists"
-                        )
-                    }) {
-                l
-            } else {
-                continue;
-            };
-            if let Overwritten::Both(.., (_, path))
-            | Overwritten::Left(.., path)
-            | Overwritten::Right(.., path)
-            | Overwritten::Pair(.., path) = map.insert(label.to_owned(), normalized.to_owned())
-            {
-                tracing::error!(
-                    atoms.label = %label,
-                    atoms.fst.path = %normalized.display(),
-                    atoms.snd.path = %path.display(),
-                    "two atoms share the same `label`"
-                );
-                return Err(de::Error::custom(
-                    "atoms must have unique labels to retain distinct identities",
-                ));
-            }
-        }
-
-        Ok(AtomMap(map))
-    }
-}
+// AtomMap deserialization is handled by RawEkalaSet::resolve_to_atom_map()
+// which properly validates label uniqueness with the correct context.
 
 impl Serialize for AtomMap {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
@@ -538,7 +441,7 @@ impl Serialize for AtomMap {
 }
 
 impl EkalaManifest {
-    /// Constructs a new Ekala manifest with the given set name
+    /// Constructs a new, empty Ekala manifest.
     pub fn new() -> Self {
         EkalaManifest {
             set: EkalaSet::new(),
@@ -546,6 +449,37 @@ impl EkalaManifest {
         }
     }
 
+    /// Opens and validates an ekala.toml from the filesystem.
+    ///
+    /// Reads the manifest, resolves all atom labels by reading each atom.toml,
+    /// and validates that no duplicate labels exist.
+    ///
+    /// # Arguments
+    /// * `path` - Path to the ekala.toml file
+    ///
+    /// # Returns
+    /// A validated `EkalaManifest` where label uniqueness is guaranteed.
+    ///
+    /// # Errors
+    /// Returns error if:
+    /// - The manifest cannot be read or parsed
+    /// - Any atom.toml cannot be read
+    /// - Duplicate labels are found (critical invariant violation)
+    pub fn open_filesystem(path: impl AsRef<Path>) -> Result<Self, DocError> {
+        let path = path.as_ref();
+        let root = path.parent().ok_or(DocError::MissingEkala)?;
+        let content = std::fs::read_to_string(path)?;
+        let raw: RawEkalaManifest = toml_edit::de::from_str(&content)?;
+
+        // Validate and resolve labels - this enforces the uniqueness invariant
+        let atom_map = raw.set.resolve_to_atom_map(root)?;
+
+        Ok(EkalaManifest {
+            set: EkalaSet { packages: atom_map },
+            metadata: raw.metadata,
+        })
+    }
+
     /// Return a reference to the EkalaSet struct
     pub fn set(&self) -> &EkalaSet {
         &self.set
@@ -565,17 +499,74 @@ impl EkalaSet {
         }
     }
 
+    /// Returns the validated AtomMap of packages.
     pub fn packages(&self) -> &AtomMap {
         &self.packages
     }
 }
 
+impl RawEkalaSet {
+    /// Resolves paths to an AtomMap using filesystem access.
+    ///
+    /// `root` should be the directory containing ekala.toml (repo root).
+    /// Each path is joined with root and the atom.toml is read to get the label.
+    /// Returns error if duplicate labels are found.
+    fn resolve_to_atom_map<P: AsRef<Path>>(&self, root: P) -> Result<AtomMap, DocError> {
+        use path_clean::PathClean;
+
+        let root = root.as_ref();
+        let mut map = BiBTreeMap::new();
+
+        for path in &self.packages {
+            let normalized = path.clean();
+            let abs_path = root.join(&normalized);
+            let manifest_path = abs_path.join(crate::ATOM_MANIFEST_NAME.as_str());
+
+            let label = match Manifest::get_atom_label(&manifest_path) {
+                Ok(l) => l,
+                Err(e) => {
+                    tracing::warn!(
+                        error = %e,
+                        path = %abs_path.display(),
+                        suggestion = "you likely want to remove it from the set, or perhaps recreate it",
+                        "atom no longer exists"
+                    );
+                    continue;
+                },
+            };
+
+            if let bimap::Overwritten::Both(.., (_, old_path))
+            | bimap::Overwritten::Left(.., old_path)
+            | bimap::Overwritten::Right(.., old_path)
+            | bimap::Overwritten::Pair(.., old_path) =
+                map.insert(label.to_owned(), normalized.to_owned())
+            {
+                tracing::error!(
+                    atoms.label = %label,
+                    atoms.fst.path = %normalized.display(),
+                    atoms.snd.path = %old_path.display(),
+                    "two atoms share the same `label`"
+                );
+                return Err(DocError::DuplicateAtoms);
+            }
+        }
+
+        Ok(AtomMap(map))
+    }
+}
+
 impl AtomMap {
     fn new() -> Self {
         AtomMap(BiBTreeMap::new())
     }
 }
 
+impl From<BiBTreeMap<Label, PathBuf>> for AtomMap {
+    fn from(map: BiBTreeMap<Label, PathBuf>) -> Self {
+        AtomMap(map)
+    }
+}
+
 impl MetaData {
     fn new() -> Self {
         MetaData {
@@ -587,6 +578,8 @@ impl MetaData {
 impl<'a, S: LocalStorage> EkalaManager<'a, S> {
     /// Create a new manifest writer, traversing upward to locate the nearest ekala.toml if
     /// necessary.
+    ///
+    /// This validates the manifest on open, ensuring label uniqueness.
     pub fn open(storage: &'a S) -> Result<Self, AtomError> {
         let path = storage
             .ekala_root_dir()
@@ -596,15 +589,24 @@ impl<'a, S: LocalStorage> EkalaManager<'a, S> {
             })?
             .join(crate::EKALA_MANIFEST_NAME.as_str());
 
-        let (doc, manifest) = {
-            let content = std::fs::read_to_string(&path).inspect_err(|_| {
-                tracing::error!(
-                    suggestion = "did you run `eka init`?",
-                    "{}",
-                    AtomError::EkalaManifest
-                )
-            })?;
-            TypedDocument::new(&content)?
+        let content = std::fs::read_to_string(&path).inspect_err(|_| {
+            tracing::error!(
+                suggestion = "did you run `eka init`?",
+                "{}",
+                AtomError::EkalaManifest
+            )
+        })?;
+
+        // Parse raw document for editing capability
+        let (doc, raw): (TypedDocument<RawEkalaManifest>, RawEkalaManifest) =
+            TypedDocument::new(&content)?;
+
+        // Validate and resolve labels
+        let root = path.parent().ok_or(AtomError::EkalaManifest)?;
+        let atom_map = raw.set.resolve_to_atom_map(root)?;
+        let manifest = EkalaManifest {
+            set: EkalaSet { packages: atom_map },
+            metadata: raw.metadata,
         };
 
         Ok(EkalaManager {
@@ -615,7 +617,9 @@ impl<'a, S: LocalStorage> EkalaManager<'a, S> {
         })
     }
 
-    /// return `AtomMap` structure from the contained Ekala manifest
+    /// Returns the validated `AtomMap` from the contained Ekala manifest.
+    ///
+    /// Since labels are validated on construction, this is infallible.
     pub fn atoms(&self) -> &AtomMap {
         self.manifest.set().packages()
     }
@@ -690,7 +694,8 @@ impl<'a, S: LocalStorage> EkalaManager<'a, S> {
     ) -> Result<(), storage::StorageError> {
         use toml_edit::{Array, Value};
 
-        if let Some(path) = self.manifest.set.packages.as_ref().get_by_left(&label) {
+        // Check for duplicate labels using the already-validated AtomMap
+        if let Some(path) = self.manifest.set().packages().as_ref().get_by_left(&label) {
             tracing::error!(
                 suggestion = "rename one of them to maintain distinct identities",
                 %label,
diff --git a/crates/atom/src/package/publish/git/inner.rs b/crates/atom/src/package/publish/git/inner.rs
index c257fb7..d4c00b2 100644
--- a/crates/atom/src/package/publish/git/inner.rs
+++ b/crates/atom/src/package/publish/git/inner.rs
@@ -39,9 +39,8 @@ use error::git::Error;
 use gix::actor::Signature;
 use gix::diff::object::Commit as AtomCommit;
 use gix::object::tree::Entry;
-use gix::objs::WriteTo;
 use gix::protocol::transport::client::Transport;
-use gix::{Object, ObjectId, Reference};
+use gix::{Object, ObjectId, Reference, Repository};
 use package::metadata::AtomPaths;
 use package::metadata::manifest::Manifest;
 use semver::Version;
@@ -55,7 +54,7 @@ use super::{
     AtomContext, AtomRef, AtomReferences, CommittedAtom, FoundAtom, GitContent, GitContext,
     GitResult, RefKind,
 };
-use crate::{Atom, AtomId, package, storage};
+use crate::{Atom, AtomId, Label, package, storage};
 
 //================================================================================================
 // Impls
@@ -76,34 +75,13 @@ impl<'a> AtomContext<'a> {
     /// This commit is self-contained and does not have any parents. It captures the state of the
     /// Atom's content tree and includes metadata such as the original source commit and path.
     pub(super) fn write_atom_commit(&self, tree: ObjectId) -> GitResult<CommittedAtom> {
-        let sig = Signature {
-            email: EMPTY_SIG.into(),
-            name: EMPTY_SIG.into(),
-            time: gix::date::Time {
-                seconds: 0,
-                offset: 0,
-            },
-        };
-        let commit = AtomCommit {
+        write_atom_commit_inner(
+            self.git.repo,
             tree,
-            parents: vec![].into(),
-            author: sig.clone(),
-            committer: sig,
-            encoding: None,
-            message: format!(
-                "publish({}): {}",
-                self.atom.spec.label(),
-                self.atom.spec.version()
-            )
-            .into(),
-            extra_headers: [
-                (ATOM_ORIGIN.into(), self.git.commit.id.to_string().into()),
-                ("format".into(), ATOM_FORMAT_VERSION.into()),
-            ]
-            .into(),
-        };
-        let id = self.git.write_object(commit.clone())?;
-        Ok(CommittedAtom { commit, id })
+            self.atom.spec.label(),
+            self.atom.spec.version(),
+            self.git.commit.id.to_string(),
+        )
     }
 }
 
@@ -157,18 +135,23 @@ impl<'a> AtomReferences<'a> {
             atom = %atom.atom.id.label(),
             remote = %remote
         );
+
+        // Capture git directory for the spawned tasks
+        let git_dir = atom.git.repo.git_dir().to_path_buf();
+
         for r in [&self.content, &self.spec, &self.origin] {
             let r = r.name().as_bstr().to_string();
             let remote = remote.clone();
             let parent = tracing::Span::current();
             let progress = atom.git.progress.clone();
+            let git_dir = git_dir.clone();
             let task = async move {
                 let _guard = parent.enter();
                 let span = tracing::info_span!("push", msg = %r, %remote);
                 crate::log::set_sub_task(&span, &format!("🚀 push: {}", r));
                 let _enter = span.enter();
                 let blocking = tokio::task::spawn_blocking(move || {
-                    git::run_git_command(&["push", &remote, format!("{r}:{r}").as_str()])
+                    git::run_git_command(&git_dir, &["push", &remote, format!("{r}:{r}").as_str()])
                 });
                 let result = blocking.await??;
 
@@ -298,11 +281,6 @@ impl<'a> GitContext<'a> {
 
         Manifest::get_atom(&content).map_err(|e| Error::Invalid(e, Box::new(path.into())))
     }
-
-    /// Writes a Git object to the repository's object database.
-    fn write_object(&self, obj: impl WriteTo) -> GitResult<gix::ObjectId> {
-        Ok(self.repo.write_object(obj).map(gix::Id::detach)?)
-    }
 }
 
 //================================================================================================
@@ -342,3 +320,35 @@ fn write_ref<'a>(
         ),
     )?)
 }
+
+pub(crate) fn write_atom_commit_inner(
+    repo: &Repository,
+    tree: ObjectId,
+    label: &Label,
+    version: &Version,
+    origin: String,
+) -> GitResult<CommittedAtom> {
+    let sig = Signature {
+        email: EMPTY_SIG.into(),
+        name: EMPTY_SIG.into(),
+        time: gix::date::Time {
+            seconds: 0,
+            offset: 0,
+        },
+    };
+    let commit = AtomCommit {
+        tree,
+        parents: vec![].into(),
+        author: sig.clone(),
+        committer: sig,
+        encoding: None,
+        message: format!("publish({}): {}", label, version).into(),
+        extra_headers: [
+            (ATOM_ORIGIN.into(), origin.into()),
+            ("format".into(), ATOM_FORMAT_VERSION.into()),
+        ]
+        .into(),
+    };
+    let id = repo.write_object(commit.clone())?.detach();
+    Ok(CommittedAtom { commit, id })
+}
diff --git a/crates/atom/src/package/publish/git/mod.rs b/crates/atom/src/package/publish/git/mod.rs
index 3f1ebc6..f94a761 100644
--- a/crates/atom/src/package/publish/git/mod.rs
+++ b/crates/atom/src/package/publish/git/mod.rs
@@ -48,13 +48,13 @@ use std::path::{Path, PathBuf};
 use gix::diff::object::Commit as AtomCommit;
 use gix::protocol::transport::client::Transport;
 use gix::{Commit, ObjectId, Reference, Remote, Repository, Tree};
+pub(crate) use inner::write_atom_commit_inner as write_atom_commit_to_repo;
 use semver::Version;
 use tokio::task::JoinSet;
 
 use super::error::git::Error;
 use super::{Builder, Content, Publish, PublishOutcome, Record, StateValidator};
 use crate::id::Label;
-use crate::package::EkalaManifest;
 use crate::package::metadata::{AtomMap, AtomPaths};
 use crate::storage::git::Root;
 use crate::storage::{NormalizeStorePath, QueryStore};
@@ -414,13 +414,52 @@ impl<'a> StateValidator for GitPublisher<'a> {
     type Publisher = GitContext<'a>;
 
     fn validate(publisher: &Self::Publisher) -> Result<AtomMap, Self::Error> {
+        use bimap::BiBTreeMap;
+        use path_clean::PathClean;
+
+        use crate::package::metadata::RawEkalaManifest;
+
         if let Some(ekala_blob) = publisher
             .tree()
             .lookup_entry_by_path(crate::EKALA_MANIFEST_NAME.as_str())?
         {
-            let manifest: EkalaManifest = toml_edit::de::from_slice(&ekala_blob.object()?.data)?;
-            let atoms = manifest.set.packages;
-            Ok(atoms)
+            let raw: RawEkalaManifest = toml_edit::de::from_slice(&ekala_blob.object()?.data)?;
+            let mut map = BiBTreeMap::new();
+
+            // Resolve labels from git tree instead of filesystem
+            for path in raw.set.packages() {
+                let normalized = path.clean();
+                let atom_toml_path = normalized.join(crate::ATOM_MANIFEST_NAME.as_str());
+
+                // Look up atom.toml in the git tree
+                let label = if let Some(atom_blob) =
+                    publisher.tree().lookup_entry_by_path(&atom_toml_path)?
+                {
+                    let atom_data = atom_blob.object()?.data.to_vec();
+                    let atom: crate::package::metadata::manifest::Manifest =
+                        toml_edit::de::from_slice(&atom_data)?;
+                    atom.package().label().to_owned()
+                } else {
+                    tracing::warn!(
+                        path = %normalized.display(),
+                        "atom.toml not found in git tree, skipping"
+                    );
+                    continue;
+                };
+
+                if let bimap::Overwritten::Both(..) | bimap::Overwritten::Left(..) =
+                    map.insert(label.to_owned(), normalized.to_owned())
+                {
+                    tracing::error!(
+                        atoms.label = %label,
+                        atoms.path = %normalized.display(),
+                        "duplicate atom label"
+                    );
+                    return Err(Error::Duplicates);
+                }
+            }
+
+            Ok(AtomMap::from(map))
         } else {
             Err(Error::NotLocallyInitialized)
         }
diff --git a/crates/atom/src/package/publish/git/test.rs b/crates/atom/src/package/publish/git/test.rs
index 45a5d50..76dc1f5 100644
--- a/crates/atom/src/package/publish/git/test.rs
+++ b/crates/atom/src/package/publish/git/test.rs
@@ -1,141 +1,26 @@
+//! Tests for git-based atom publishing.
+
 use std::collections::HashMap;
-use std::os::unix::fs::MetadataExt;
-use std::path::PathBuf;
-use std::str::FromStr;
 
 use anyhow::{Context, anyhow};
+use gix::ThreadSafeRepository;
 use gix::prelude::ReferenceExt;
-use gix::{ObjectId, ThreadSafeRepository};
 
 use super::super::{Content, Publish, Record};
-use crate::storage::{EkalaStorage, git};
-
-//================================================================================================
-// Traits
-//================================================================================================
-
-trait MockAtom {
-    async fn mock(&self, id: &str, version: &str) -> Result<(PathBuf, ObjectId), anyhow::Error>;
-}
+use crate::storage::{Init, QueryStore};
+use crate::test::harness::{MockAtom, init_repo_and_remote, init_tracing};
 
 //================================================================================================
-// Impls
+// Tests
 //================================================================================================
 
-impl MockAtom for gix::ThreadSafeRepository {
-    async fn mock(&self, label: &str, version: &str) -> Result<(PathBuf, ObjectId), anyhow::Error> {
-        use gix::objs::Tree;
-        use gix::objs::tree::Entry;
-        use semver::Version;
-
-        use crate::EkalaManager;
-
-        let repo = self.to_thread_local();
-        let work_dir = repo.workdir().context("No workdir")?;
-        let atom_dir = work_dir.join(label);
-        let atom_file = atom_dir.join(crate::ATOM_MANIFEST_NAME.as_str());
-
-        let mut ekala = EkalaManager::open(self)?;
-        ekala
-            .new_atom_at_path(label.try_into()?, &atom_dir, Version::from_str(version)?)
-            .await?;
-
-        let buf = std::fs::read_to_string(&atom_file)?;
-
-        let mode = atom_file.metadata()?.mode();
-        let filename = atom_file
-            .strip_prefix(&atom_dir)?
-            .display()
-            .to_string()
-            .into();
-        let oid = repo.write_blob(buf.as_bytes())?.detach();
-        let entry = Entry {
-            mode: TryFrom::try_from(mode)
-                .map_err(|m| anyhow::anyhow!("invalid entry mode: {}", m))?,
-            filename,
-            oid,
-        };
-
-        let tree = Tree {
-            entries: vec![entry],
-        };
-
-        let oid = repo.write_object(tree)?.detach();
-
-        let filename = atom_dir
-            .to_path_buf()
-            .strip_prefix(work_dir)?
-            .display()
-            .to_string()
-            .into();
-
-        let entry_dir = Entry {
-            mode: TryFrom::try_from(0o40000)
-                .map_err(|m| anyhow::anyhow!("invalid entry mode: {}", m))?,
-            filename,
-            oid,
-        };
-
-        let filename = crate::EKALA_MANIFEST_NAME.to_string().into();
-        let buf = std::fs::read(
-            repo.ekala_root_dir()?
-                .join(crate::EKALA_MANIFEST_NAME.as_str()),
-        )?;
-        let oid = repo.write_blob(buf)?.detach();
-
-        let entry = Entry {
-            mode: TryFrom::try_from(mode)
-                .map_err(|m| anyhow::anyhow!("invalid entry mode: {}", m))?,
-            filename,
-            oid,
-        };
-
-        let tree = Tree {
-            entries: vec![entry, entry_dir],
-        };
-
-        let oid = repo.write_object(tree)?.detach();
-
-        let head = repo.head_id()?;
-        let head_ref = repo.head_ref()?.context("detached HEAD")?;
-
-        let atom_oid = repo
-            .commit(
-                head_ref.name().as_bstr(),
-                format!("init: {}", label),
-                oid,
-                vec![head],
-            )?
-            .detach();
-
-        Ok((atom_file, atom_oid))
-    }
-}
-
-//================================================================================================
-// Functions
-//================================================================================================
-
-use tracing_subscriber::filter::EnvFilter;
-use tracing_subscriber::fmt;
-use tracing_subscriber::layer::SubscriberExt;
-use tracing_subscriber::util::SubscriberInitExt;
-fn init_tracing() {
-    tracing_subscriber::registry()
-        .with(fmt::layer().compact())  // Or .pretty() for nicer formatting
-        .with(EnvFilter::from_default_env())  // Respects RUST_LOG env var
-        .init();
-}
-
 #[tokio::test]
 async fn publish_atom() -> Result<(), anyhow::Error> {
     use super::{Builder, GitPublisher};
     use crate::id::Label;
-    use crate::storage::{Init, QueryStore};
     init_tracing();
 
-    let (repo_dir, _remote) = git::test::init_repo_and_remote()?;
-    std::env::set_current_dir(&repo_dir)?;
+    let (repo_dir, _remote) = init_repo_and_remote()?;
     let repo = ThreadSafeRepository::open(repo_dir.as_ref())?;
     let repo = repo.to_thread_local();
     let remote = repo.find_remote("origin")?;
@@ -150,10 +35,15 @@ async fn publish_atom() -> Result<(), anyhow::Error> {
     let repo = repo.to_thread_local();
 
     let (paths, publisher) = GitPublisher::new(&repo, "origin", "HEAD", progress)?.build()?;
+
     let path = paths
         .as_ref()
         .get_by_left(&Label::try_from(label)?)
-        .context("path is messed up")?;
+        .context(format!(
+            "Could not find label '{}' in paths: {:?}",
+            label,
+            paths.as_ref()
+        ))?;
     let result = publisher.publish_atom(path, &HashMap::new())?;
     let mut errors = Vec::with_capacity(1);
     publisher.await_pushes(&mut errors).await;
diff --git a/crates/atom/src/package/publish/mod.rs b/crates/atom/src/package/publish/mod.rs
index e285934..91fdd99 100644
--- a/crates/atom/src/package/publish/mod.rs
+++ b/crates/atom/src/package/publish/mod.rs
@@ -92,12 +92,12 @@ mod private {
 // Constants
 //================================================================================================
 
+const EMPTY_SIG: &str = "";
 const ATOM_FORMAT_VERSION: &str = "pre1";
 const ATOM_MANIFEST: &str = "manifest";
 const ATOM_META_REF: &str = "meta";
 const ATOM_ORIGIN: &str = "origin";
 const ATOM_REF: &str = "atoms";
-const EMPTY_SIG: &str = "";
 const STORE_ROOT: &str = "eka";
 
 //================================================================================================
diff --git a/crates/atom/src/package/resolve/direct/mod.rs b/crates/atom/src/package/resolve/direct/mod.rs
index 5e977e9..3381ab6 100644
--- a/crates/atom/src/package/resolve/direct/mod.rs
+++ b/crates/atom/src/package/resolve/direct/mod.rs
@@ -128,7 +128,11 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
                     let (_, dep) = self.resolve_nix(dep.to_owned(), Some(name)).await?;
                     self.lock.deps.as_mut().insert(key, dep);
                 }
-            } else if let Ok((_, dep)) = self.resolve_nix(dep.to_owned(), Some(name)).await {
+            } else if let Ok((_, dep)) = self
+                .resolve_nix(dep.to_owned(), Some(name))
+                .await
+                .map_err(|e| tracing::error!("{}", e))
+            {
                 self.lock.deps.as_mut().insert(key, dep);
             } else {
                 tracing::warn!(message = Self::RESOLUTION_ERR_MSG, direct.nix = %name);
@@ -374,6 +378,7 @@ impl NixGit {
             url: self.git.to_owned(),
             rev: GitDigest::Sha1(id),
             version,
+            owner: None,
         })
     }
 
diff --git a/crates/atom/src/package/resolve/mod.rs b/crates/atom/src/package/resolve/mod.rs
index 3c1c4ed..7b56a68 100644
--- a/crates/atom/src/package/resolve/mod.rs
+++ b/crates/atom/src/package/resolve/mod.rs
@@ -44,17 +44,17 @@ use lock::direct::NixUrls;
 use lock::{AtomDep, SetDetails};
 use metadata::manifest::{AtomReq, AtomWriter, SetMirror, WriteDeps};
 use metadata::{DocError, GitDigest, lock};
-use semver::{Prerelease, VersionReq};
+use semver::VersionReq;
 use sets::{MirrorResult, ResolvedAtom, ResolvedSets, SetResolver};
-use storage::UnpackedRef;
-use storage::git::{AtomQuery, Root};
+use storage::git::{AtomQuery, Root, cache_repo};
+use storage::{LocalStorage, QueryVersion, RemoteAtomCache, UnpackedRef};
 use uri::Uri;
 
 use super::{ValidManifest, metadata, sets};
-use crate::storage::{LocalStorage, QueryVersion};
 use crate::{ATOM_MANIFEST_NAME, AtomId, BoxError, ManifestWriter, id, storage, uri};
 
 mod direct;
+mod sat;
 
 //================================================================================================
 // Impls
@@ -503,8 +503,7 @@ impl Uri {
     ) -> Result<(AtomReq, AtomDep), crate::storage::git::Error> {
         let url = self.url();
         let label = self.label();
-        if url.is_some_and(|u| u.scheme != gix::url::Scheme::File) {
-            let url = url.unwrap();
+        if let Some(url) = url {
             let atoms = url.get_atoms(transport)?;
             let ObjectId::Sha1(root) = *atoms.calculate_genesis()?;
             let (version, oid) = <gix::url::Url as QueryVersion>::process_highest_match(
@@ -522,19 +521,17 @@ impl Uri {
             let id = AtomId::construct(&atoms, label.to_owned())?;
             Ok((
                 atom_req,
-                AtomDep::new(
+                AtomDep::new_direct(
                     label.to_owned(),
                     version,
                     GitDigest::Sha1(root),
                     match oid {
-                        ObjectId::Sha1(bytes) => Some(GitDigest::Sha1(bytes)),
+                        ObjectId::Sha1(bytes) => GitDigest::Sha1(bytes),
                     },
-                    Some(url.to_owned()),
                     id.into(),
                 ),
             ))
         } else {
-            // implement path resolution for atoms
             tracing::warn!("specifying atoms by path not implemented");
             todo!()
         }
@@ -549,7 +546,17 @@ impl Uri {
 
 impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
     /// Adds a user-requested atom URI to the manifest and lock files, ensuring they remain in sync.
-    pub fn add_uri(&mut self, uri: Uri, set_tag: Option<Tag>) -> Result<(), storage::git::Error> {
+    ///
+    /// # Parameters
+    /// - `uri`: The atom URI to add
+    /// - `set_tag`: Optional tag for the package set
+    /// - `additional_mirrors`: Additional mirrors to add to the set (must have matching genesis)
+    pub fn add_uri(
+        &mut self,
+        uri: Uri,
+        set_tag: Option<Tag>,
+        additional_mirrors: Vec<SetMirror>,
+    ) -> Result<(), storage::git::Error> {
         let mirror = if let Some(url) = uri.url() {
             SetMirror::Url(url.to_owned())
         } else {
@@ -557,6 +564,9 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
         };
         let (atom_req, lock_entry) = self.resolve_uri(&uri, &mirror)?;
 
+        // Get the ground truth Root from the initial mirror for validating additional mirrors
+        let expected_root = self.get_mirror_genesis(&mirror)?;
+
         let label = lock_entry.label().to_owned();
         let id = AtomId::from(&lock_entry);
         let set_tag = self.get_set_tag(&lock_entry, &uri, set_tag);
@@ -567,11 +577,52 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
         atom_writer.write_dep(label, self.doc_mut())?;
         self.insert_or_update_and_log(Either::Left(id.to_owned()), &lock::Dep::Atom(lock_entry));
 
-        self.update_lock_set(set, mirror, set_tag);
+        self.update_lock_set(set, mirror, set_tag.clone());
+
+        // Validate and add each additional mirror
+        for additional_mirror in additional_mirrors {
+            match self.get_mirror_genesis(&additional_mirror) {
+                Ok(genesis) if genesis == expected_root => {
+                    self.update_lock_set(set, additional_mirror.clone(), set_tag.clone());
+                    tracing::info!(mirror = %additional_mirror, "added mirror to set");
+                },
+                Ok(genesis) => {
+                    tracing::warn!(
+                        mirror = %additional_mirror,
+                        expected = %*expected_root,
+                        actual = %*genesis,
+                        "mirror genesis mismatch; skipping"
+                    );
+                },
+                Err(e) => {
+                    tracing::warn!(
+                        mirror = %additional_mirror,
+                        error = %e,
+                        "failed to get mirror genesis; skipping"
+                    );
+                },
+            }
+        }
 
         Ok(())
     }
 
+    /// Gets the genesis Root for a mirror.
+    fn get_mirror_genesis(&self, mirror: &SetMirror) -> Result<Root, storage::git::Error> {
+        match mirror {
+            SetMirror::Local => self
+                .resolved
+                .ekala
+                .storage
+                .ekala_genesis(None)
+                .map_err(|e| {
+                    tracing::error!(message = %e);
+                    storage::git::Error::RootNotFound
+                }),
+            SetMirror::Url(url) => storage::git::query_root(url),
+        }
+    }
+
     /// Atomically writes the changes to the manifest and lock files on disk.
     /// This method should be called last, after all changes have been processed.
     ///
@@ -608,40 +659,31 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
     }
 
     /// Removes any dependencies from the lockfile that are no longer present in the
-    /// manifest, ensuring the lockfile only contains entries that are still relevant,
-    /// then calls into synchronization logic to ensure consistency.
+    /// manifest, ensuring the lockfile only contains entries that are still relevant.
+    ///
+    /// Note: Atom deps are managed entirely by the SAT resolver now - this method
+    /// only handles direct (non-atom) deps like Nix, NixGit, NixTar, etc.
     pub(super) fn sanitize(&mut self, manifest: &ValidManifest) {
         let manifest = manifest.as_ref();
-        self.lock.deps.as_mut().retain(|_, dep| match dep {
-            lock::Dep::Atom(atom_dep) => {
-                if let Some(SetDetails { tag: name, .. }) = self.lock.sets.get(&atom_dep.set()) {
-                    if let Some(set) = manifest.deps().from().get(name) {
-                        return set.contains_key(atom_dep.label())
-                            && (atom_dep.version().pre.is_empty()
-                                || self
-                                    .resolved
-                                    .ekala
-                                    .manifest
-                                    .set
-                                    .packages
-                                    .as_ref()
-                                    .contains_left(atom_dep.label()));
-                    } else {
-                        false
-                    };
-                }
-                false
-            },
-            lock::Dep::Nix(nix) => manifest.deps().direct().nix().contains_key(nix.name()),
-            lock::Dep::NixGit(nix_git) => {
-                manifest.deps().direct().nix().contains_key(&nix_git.name)
-            },
-            lock::Dep::NixTar(nix_tar) => {
-                manifest.deps().direct().nix().contains_key(&nix_tar.name)
-            },
-            lock::Dep::NixSrc(build_src) => {
-                manifest.deps().direct().nix().contains_key(&build_src.name)
-            },
+
+        // Clear all atom deps - SAT resolver will rebuild the correct set
+        // This ensures transitive deps are properly managed
+        self.lock.deps.as_mut().retain(|_key, dep| {
+            match dep {
+                // Atom deps are managed by SAT resolver - clear them all
+                lock::Dep::Atom(_) => false,
+                // Direct deps: keep if still in manifest
+                lock::Dep::Nix(nix) => manifest.deps().direct().nix().contains_key(nix.name()),
+                lock::Dep::NixGit(nix_git) => {
+                    manifest.deps().direct().nix().contains_key(&nix_git.name)
+                },
+                lock::Dep::NixTar(nix_tar) => {
+                    manifest.deps().direct().nix().contains_key(&nix_tar.name)
+                },
+                lock::Dep::NixSrc(build_src) => {
+                    manifest.deps().direct().nix().contains_key(&build_src.name)
+                },
+            }
         });
     }
 
@@ -649,115 +691,104 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
     /// It resolves any new dependencies, updates existing ones if their version
     /// requirements have changed, and ensures the lockfile is fully consistent.
     pub(super) async fn synchronize(&mut self, manifest: &ValidManifest) -> Result<(), DocError> {
-        self.synchronize_atoms(manifest)?;
+        self.set_lock_compose(manifest)?;
+        let transitive_nix_deps = self.synchronize_atoms(manifest)?;
+        self.synchronize_transitive_nix_deps(transitive_nix_deps)
+            .await?;
         self.synchronize_direct(manifest).await?;
         Ok(())
     }
 
-    fn synchronize_atoms(&mut self, manifest: &ValidManifest) -> Result<(), DocError> {
-        for (set_tag, set) in manifest.as_ref().deps().from() {
-            let maybe_root = self
-                .resolved
-                .roots()
-                .get(&Either::Left(set_tag.to_owned()))
-                .map(ToOwned::to_owned);
-            if let Some(root) = maybe_root {
-                for (label, req) in set {
-                    tracing::debug!(
-                        atom.label = %label,
-                        atom.specified = %req,
-                        set = %set_tag,
-                        "checking sync status"
-                    );
-                    let id = AtomId::from((root, label.to_owned()));
-                    self.synchronize_atom(req.to_owned(), id.to_owned(), set_tag.to_owned())
-                        .map_err(|error| {
-                            tracing::error!(
-                                atom.label = %label,
-                                atom.requested = %req,
-                                set = %set_tag,
-                                %error, "lock synchronization failed"
-                            );
-                            DocError::SyncFailed
-                        })?;
+    fn synchronize_atoms(
+        &mut self,
+        manifest: &ValidManifest,
+    ) -> Result<Vec<sat::CollectedNixDep>, DocError> {
+        use sat::{AtomResolver, ResolutionError};
+
+        // Create a SAT resolver for transitive dependency resolution
+        let resolver = AtomResolver::new(&self.resolved);
+
+        // Perform SAT-based resolution
+        match resolver.resolve(manifest) {
+            Ok(result) => {
+                tracing::info!(
+                    deps_count = result.deps.len(),
+                    nix_deps_count = result.nix_deps.len(),
+                    "SAT resolution completed successfully"
+                );
+
+                // Update lock with all resolved deps (direct + transitive)
+                for dep in result.deps {
+                    let atom_dep: AtomDep = dep.into();
+                    let id = AtomId::from(&atom_dep);
+                    self.insert_or_update_and_log(Either::Left(id), &lock::Dep::Atom(atom_dep));
                 }
-            } else {
-                tracing::warn!(
-                    message = "set was not resolved to an origin id, can't syncrhonize it",
-                    set = %set_tag,
+
+                // Return collected nix deps for async resolution
+                Ok(result.nix_deps)
+            },
+            Err(ResolutionError::Unsolvable(msg)) => {
+                tracing::error!(
+                    error = %msg,
+                    "Dependency resolution failed - no valid solution exists"
                 );
-            }
+                Err(DocError::SyncFailed)
+            },
+            Err(ResolutionError::Cancelled) => {
+                tracing::warn!("Dependency resolution was cancelled");
+                Err(DocError::SyncFailed)
+            },
+            Err(e) => {
+                tracing::error!(error = %e, "Dependency resolution error");
+                Err(DocError::SyncFailed)
+            },
         }
-        Ok(())
     }
 
-    /// Synchronizes a single atom's lockfile entry with the manifest requirements.
-    ///
-    /// This function ensures that the lockfile contains the correct version and metadata
-    /// for an atom specified in the manifest. It handles both new atoms (not yet in lockfile)
-    /// and existing atoms that may need version updates.
-    ///
-    /// # Parameters
-    ///
-    /// - `req`: The version requirement specified in the manifest for this atom
-    /// - `id`: The unique identifier for this atom within its package set
-    /// - `set_tag`: The name of the package set containing this atom
-    ///
-    /// # Returns
-    ///
-    /// Returns `Ok(())` on success, or a `git::Error` if:
-    /// - No matching version can be found in resolved atoms
-    /// - Local resolution fails when remote resolution is unavailable
-    ///
-    /// # Algorithm
-    ///
-    /// 1. **Check Lockfile Presence**: Determine if atom already exists in lockfile
-    /// 2. **New Atom Resolution**: If not present, resolve to highest matching version
-    /// 3. **Existing Atom Validation**: If present, check if current version still matches
-    ///    requirement
-    /// 4. **Version Update**: If requirement no longer matches, resolve to new version
-    ///
-    /// # Edge Cases
-    ///
-    /// - **New Atom**: Not in lockfile - resolves and adds new entry
-    /// - **Version Mismatch**: Existing atom version doesn't satisfy new requirement - updates
-    /// - **Version Match**: Existing atom still valid - no changes needed
-    /// - **Resolution Failure**: No version satisfies requirement - returns error
-    ///
-    /// # Assumptions
-    ///
-    /// - Manifest requirements are valid and parseable
-    /// - Resolved atoms contain all available versions for this atom
-    /// - Lockfile structure is consistent with manifest
-    ///
-    /// # Integration
+    /// Resolves and locks nix deps collected from transitive atom manifests.
     ///
-    /// Called during manifest synchronization for each atom in each package set.
-    /// Part of the broader dependency resolution and locking process that ensures
-    /// reproducible builds by recording exact versions and commit hashes.
-    fn synchronize_atom(
+    /// These are nix deps declared in atoms that our root depends on transitively.
+    /// Each dep is resolved using the same logic as direct nix deps, but with the
+    /// `owner` field set to indicate which atom it belongs to.
+    async fn synchronize_transitive_nix_deps(
         &mut self,
-        req: VersionReq,
-        id: AtomId<Root>,
-        set_tag: Tag,
-    ) -> Result<(), crate::storage::git::Error> {
-        if !self
-            .lock
-            .deps
-            .as_ref()
-            .contains_key(&either::Either::Left(id.to_owned()))
-        {
-            self.lock_atom(req, id, set_tag)?;
-        } else if let Some(lock::Dep::Atom(dep)) = self
-            .lock
-            .deps
-            .as_ref()
-            .get(&either::Either::Left(id.to_owned()))
-            && dep.rev().is_some()
-            && !req.matches(dep.version())
-        {
-            self.lock_atom(req, id, set_tag)?;
+        nix_deps: Vec<sat::CollectedNixDep>,
+    ) -> Result<(), DocError> {
+        for collected in nix_deps {
+            tracing::debug!(
+                name = %collected.name,
+                owner = %collected.owner,
+                "resolving transitive nix dependency"
+            );
+
+            // Resolve the nix dep using existing infrastructure
+            match self
+                .resolve_nix(collected.fetch.clone(), Some(&collected.name))
+                .await
+            {
+                Ok((key, mut lock_dep)) => {
+                    // Set the owner field on the resolved dep
+                    match &mut lock_dep {
+                        lock::Dep::Nix(dep) => dep.owner = Some(collected.owner),
+                        lock::Dep::NixGit(dep) => dep.owner = Some(collected.owner),
+                        lock::Dep::NixTar(dep) => dep.owner = Some(collected.owner),
+                        lock::Dep::NixSrc(dep) => dep.owner = Some(collected.owner),
+                        lock::Dep::Atom(_) => {}, // shouldn't happen
+                    }
+                    self.insert_or_update_and_log(Either::Right(key), &lock_dep);
+                },
+                Err(e) => {
+                    tracing::error!(
+                        name = %collected.name,
+                        owner = %collected.owner,
+                        error = %e,
+                        "failed to resolve transitive nix dependency"
+                    );
+                    // Continue with other deps rather than failing entirely
+                },
+            }
         }
+
         Ok(())
     }
 
@@ -792,7 +823,8 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
     ///
     /// - **No Remote Match**: Falls back to local resolution
     /// - **No Local Repo**: Returns error if both remote and local resolution fail
-    /// - **Local Resolution Success**: Uses local version with "local" prerelease tag
+    /// - **Local Resolution Success**: Uses local version with prerelease tag calculated after
+    ///   building atom commit
     /// - **Version Conflicts**: Prefers remote resolution, only uses local as fallback
     ///
     /// # Assumptions
@@ -888,7 +920,8 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
     ///    - Construct atom ID from root and URI label
     ///    - Find the atom's manifest file in the local package directory
     ///    - Parse the manifest and validate it matches the requested atom
-    ///    - Create a dependency with a "local" prerelease version tag
+    ///    - Import into local atom store as a dependency with a prerelease version tag based on
+    ///      atom commit
     ///
     /// # Edge Cases
     ///
@@ -920,7 +953,7 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
             /* local store has a mirror which resolved this atom successfully */
             Ok(res)
         } else {
-            let path = self
+            let rel_path = self
                 .resolved
                 .ekala
                 .manifest
@@ -929,6 +962,14 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
                 .as_ref()
                 .get_by_left(uri.label())
                 .ok_or(DocError::NoLocal)?;
+
+            // Join relative path with ekala root to get absolute path
+            let root_dir = self.resolved.ekala.storage.ekala_root_dir().map_err(|e| {
+                tracing::error!(message = %e);
+                DocError::MissingEkala
+            })?;
+            let path = root_dir.join(rel_path);
+
             let content = std::fs::read_to_string(path.join(ATOM_MANIFEST_NAME.as_str()))?;
             let atom = ValidManifest::get_atom(&content)?;
             if atom.label() != uri.label() {
@@ -945,13 +986,12 @@ impl<'a, S: LocalStorage> ManifestWriter<'a, S> {
                     .to_owned(),
             );
             let id = AtomId::from((root, uri.label().to_owned()));
-            let mut version = atom.version().clone();
-            version.pre = Prerelease::new("local")?;
-            let unpacked = UnpackedRef {
-                id,
-                version,
-                rev: None,
-            };
+
+            let cache = &cache_repo()?.to_thread_local();
+
+            let (version, local_atom) = cache.path_to_cache(&path)?;
+
+            let unpacked = UnpackedRef::new(id, version, local_atom.id);
             let dep = AtomDep::from(ResolvedAtom {
                 unpacked,
                 remotes: BTreeSet::new(),
diff --git a/crates/atom/src/package/resolve/sat.rs b/crates/atom/src/package/resolve/sat.rs
new file mode 100644
index 0000000..09eff9c
--- /dev/null
+++ b/crates/atom/src/package/resolve/sat.rs
@@ -0,0 +1,1365 @@
+//! SAT-based dependency resolution for atoms using resolvo.
+//!
+//! This module provides the core types and traits for resolving atom dependencies
+//! using a CDCL SAT solver (resolvo). Key components include:
+//!
+//! - [`SemverVersionSet`] - Wrapper for `semver::VersionReq` implementing resolvo's `VersionSet`
+//!   trait
+//! - [`AtomSolvableRecord`] - Metadata associated with each solvable (version candidate)
+//! - [`DiscoveryState`] - Tracks which packages have completed candidate discovery
+//! - [`ManifestCache`] - Tracks which manifests have been fetched and cached
+//!
+//! ## Architecture
+//!
+//! The resolution process follows these phases:
+//! 1. **Discovery** - Query remote refs for available versions (cheap ref queries)
+//! 2. **Candidate Registration** - Intern packages and candidates into the pool
+//! 3. **SAT Solving** - resolvo explores the search space using CDCL
+//! 4. **Lazy Manifest Fetching** - Fetch manifests only when `get_dependencies` is called
+//! 5. **Solution Extraction** - Extract resolved versions and build the lock file
+//!
+//! See ADR-0015 for the full implementation plan.
+
+use std::cell::RefCell;
+use std::collections::{HashMap, HashSet};
+use std::fmt::{self, Display};
+use std::hash::Hash;
+
+use either::Either;
+use gix::protocol::transport::client::Transport;
+use resolvo::utils::{Pool, VersionSet};
+use resolvo::{
+    Candidates, Condition, ConditionId, ConditionalRequirement, Dependencies, DependencyProvider,
+    HintDependenciesAvailable, Interner, KnownDependencies, NameId, Problem, Requirement,
+    SolvableId, Solver, StringId, UnsolvableOrCancelled, VersionSetId,
+};
+use semver::{Version, VersionReq};
+
+use crate::id::{AtomDigest, Name, Tag};
+use crate::package::metadata::GitDigest;
+use crate::package::metadata::manifest::SetMirror;
+use crate::package::metadata::manifest::direct::NixFetch;
+use crate::package::sets::ResolvedSets;
+use crate::storage::git::{Root, to_id};
+use crate::storage::{LocalStorage, RemoteAtomCache};
+use crate::{AtomId, BoxError, Compute, Label, ValidManifest};
+
+//================================================================================================
+// Types
+//================================================================================================
+
+/// A version set based on semver version requirements.
+///
+/// This type wraps `semver::VersionReq` to implement resolvo's `VersionSet` trait,
+/// enabling semver-based constraint satisfaction during dependency resolution.
+///
+/// The `VersionSet` trait requires:
+/// - `Clone + Eq + Hash` for interning in the pool
+/// - Associated type `V: Display` for the version type
+///
+/// # Example
+///
+/// ```rust
+/// use atom::package::resolve::sat::SemverVersionSet;
+/// use semver::VersionReq;
+///
+/// let req = VersionReq::parse("^1.0").unwrap();
+/// let version_set = SemverVersionSet(req);
+///
+/// // Can be used with resolvo's Pool
+/// // pool.intern_version_set(name_id, version_set);
+/// ```
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct SemverVersionSet(pub semver::VersionReq);
+
+impl SemverVersionSet {
+    /// Creates a new `SemverVersionSet` from a version requirement string.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the string cannot be parsed as a valid semver requirement.
+    #[cfg(test)]
+    pub fn parse(s: &str) -> Result<Self, semver::Error> {
+        semver::VersionReq::parse(s).map(SemverVersionSet)
+    }
+
+    /// Returns true if the given version matches this version requirement.
+    pub fn matches(&self, version: &semver::Version) -> bool {
+        self.0.matches(version)
+    }
+
+    /// Returns a reference to the inner `VersionReq`.
+    #[cfg(test)]
+    pub fn inner(&self) -> &semver::VersionReq {
+        &self.0
+    }
+}
+
+impl Display for SemverVersionSet {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl From<semver::VersionReq> for SemverVersionSet {
+    fn from(req: semver::VersionReq) -> Self {
+        SemverVersionSet(req)
+    }
+}
+
+impl VersionSet for SemverVersionSet {
+    type V = AtomSolvableRecord;
+}
+
+/// Metadata associated with each solvable (version candidate) in the pool.
+///
+/// This record stores information about a specific version of an atom that
+/// is needed during resolution and for generating the lock file.
+///
+/// The record is stored as the `V` (version) type parameter of resolvo's `Pool<VS, N>`,
+/// meaning each solvable in the pool contains this metadata.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct AtomSolvableRecord {
+    /// The semantic version of this candidate.
+    pub version: semver::Version,
+
+    /// The Git commit revision for this version.
+    ///
+    /// This is extracted from the ref name (e.g., `refs/eka/atoms/{label}/{version}`)
+    /// during discovery and verified during fetch.
+    pub rev: GitDigest,
+
+    /// The computed BLAKE3 atom digest.
+    ///
+    /// This uniquely identifies the atom (root + label) and is used
+    /// for looking up atoms in the lock file.
+    pub atom_id: AtomDigest,
+
+    /// The full AtomId with Root, needed for fetching manifests.
+    /// This is stored in addition to the digest for efficient lookup.
+    pub package: AtomId<Root>,
+
+    /// Whether the manifest for this version has been fetched and cached.
+    ///
+    /// When true, we can retrieve dependencies from the local cache rather
+    /// than fetching from the remote. This flag is updated after successful
+    /// manifest fetches.
+    pub manifest_cached: bool,
+}
+
+impl Display for AtomSolvableRecord {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.version)
+    }
+}
+
+impl PartialOrd for AtomSolvableRecord {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for AtomSolvableRecord {
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        // Sort by version primarily (for sorting candidates)
+        self.version.cmp(&other.version)
+    }
+}
+
+impl Hash for AtomSolvableRecord {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        // Hash by version and atom_id for deduplication
+        self.version.hash(state);
+        self.atom_id.hash(state);
+    }
+}
+
+//================================================================================================
+// Resolution State Tracking
+//================================================================================================
+
+#[cfg(test)]
+use std::collections::BTreeMap;
+
+/// Tracks which packages have completed candidate discovery.
+///
+/// Used to avoid redundant ref queries for the same package.
+#[derive(Default, Debug)]
+#[cfg(test)]
+pub struct DiscoveryState {
+    /// Packages that have completed discovery.
+    pub discovered: BTreeMap<AtomDigest, DiscoveryStatus>,
+}
+
+#[cfg(test)]
+/// Status of candidate discovery for a package.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum DiscoveryStatus {
+    /// Discovery is pending/in-progress.
+    Pending,
+    /// Discovery completed successfully with the number of candidates found.
+    Completed(usize),
+    /// Discovery failed with an error message.
+    Failed(String),
+}
+
+#[cfg(test)]
+impl DiscoveryState {
+    /// Creates a new empty discovery state.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Marks a package as having pending discovery.
+    pub fn mark_pending(&mut self, atom_id: AtomDigest) {
+        self.discovered.insert(atom_id, DiscoveryStatus::Pending);
+    }
+
+    /// Marks a package discovery as completed.
+    pub fn mark_completed(&mut self, atom_id: AtomDigest, count: usize) {
+        self.discovered
+            .insert(atom_id, DiscoveryStatus::Completed(count));
+    }
+
+    /// Marks a package discovery as failed.
+    pub fn mark_failed(&mut self, atom_id: AtomDigest, error: String) {
+        self.discovered
+            .insert(atom_id, DiscoveryStatus::Failed(error));
+    }
+
+    /// Returns true if discovery has been attempted for this package.
+    pub fn is_discovered(&self, atom_id: &AtomDigest) -> bool {
+        self.discovered.contains_key(atom_id)
+    }
+
+    /// Returns the discovery status for a package.
+    pub fn status(&self, atom_id: &AtomDigest) -> Option<&DiscoveryStatus> {
+        self.discovered.get(atom_id)
+    }
+}
+
+//================================================================================================
+// Manifest Cache State
+//================================================================================================
+
+/// Tracks which manifests have been fetched and cached.
+///
+/// This is used to avoid redundant manifest fetches during resolution.
+#[derive(Default, Debug)]
+#[cfg(test)]
+pub struct ManifestCache {
+    /// Set of atom versions whose manifests have been fetched.
+    ///
+    /// Key is (AtomDigest, Version) to uniquely identify a specific version.
+    pub cached: BTreeMap<(AtomDigest, semver::Version), ManifestCacheEntry>,
+}
+
+/// A cached manifest entry.
+#[cfg(test)]
+#[derive(Clone, Debug)]
+pub struct ManifestCacheEntry {
+    /// The parsed dependencies from the manifest.
+    ///
+    /// Each entry is (dependency_atom_id, version_requirement).
+    pub dependencies: Vec<(AtomDigest, semver::VersionReq)>,
+}
+
+#[cfg(test)]
+impl ManifestCache {
+    /// Creates a new empty manifest cache.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Checks if a manifest is cached for the given atom version.
+    pub fn is_cached(&self, atom_id: &AtomDigest, version: &semver::Version) -> bool {
+        self.cached.contains_key(&(*atom_id, version.clone()))
+    }
+
+    /// Gets a cached manifest entry.
+    pub fn get(
+        &self,
+        atom_id: &AtomDigest,
+        version: &semver::Version,
+    ) -> Option<&ManifestCacheEntry> {
+        self.cached.get(&(*atom_id, version.clone()))
+    }
+
+    /// Inserts a manifest into the cache.
+    pub fn insert(
+        &mut self,
+        atom_id: AtomDigest,
+        version: semver::Version,
+        dependencies: Vec<(AtomDigest, semver::VersionReq)>,
+    ) {
+        self.cached
+            .insert((atom_id, version), ManifestCacheEntry { dependencies });
+    }
+}
+
+/// Resolution context holding all state needed for dependency resolution
+pub struct AtomResolver<'a, S: LocalStorage> {
+    /// The resolvo pool for interning - package names are AtomId<Root>, solvable records are
+    /// AtomSolvableRecord
+    pool: Pool<SemverVersionSet, AtomId<Root>>,
+
+    /// Mapping from AtomId to available versions discovered via ref queries
+    /// Uses RefCell for interior mutability since DependencyProvider trait methods use &self
+    discovered_candidates: RefCell<HashMap<AtomId<Root>, Vec<DiscoveredVersion>>>,
+
+    /// Cache of fetched manifests: (AtomDigest, Version) -> parsed dependencies
+    /// Uses RefCell for interior mutability since DependencyProvider trait methods use &self
+    manifest_cache: RefCell<HashMap<(AtomDigest, Version), Vec<AtomDependency>>>,
+
+    /// Set of solvables whose manifests are locally cached (cheap deps access)
+    /// Uses RefCell for interior mutability since DependencyProvider trait methods use &self
+    locally_available: RefCell<HashSet<SolvableId>>,
+
+    /// Reference to resolved sets from manifest processing
+    resolved_sets: &'a ResolvedSets<'a, S>,
+
+    /// Transports for remote operations (reusable connections)
+    /// Uses RefCell for interior mutability since DependencyProvider trait methods use &self
+    transports: RefCell<HashMap<gix::Url, Box<dyn Transport + Send>>>,
+
+    /// Nix deps collected from transitive atom manifests
+    /// Uses RefCell for interior mutability since DependencyProvider trait methods use &self
+    collected_nix_deps: RefCell<Vec<CollectedNixDep>>,
+}
+
+#[derive(Clone, Debug)]
+struct DiscoveredVersion {
+    version: Version,
+    solvable_id: SolvableId,
+}
+
+#[derive(Clone, Debug)]
+struct AtomDependency {
+    /// Target atom identity (Root + Label)
+    target: AtomId<Root>,
+    /// Version requirement
+    version_req: VersionReq,
+}
+
+/// A nix dep collected from a transitive atom's manifest.
+#[derive(Clone, Debug)]
+pub struct CollectedNixDep {
+    /// Name of the nix dep
+    pub name: Name,
+    /// The nix fetch specification
+    pub fetch: NixFetch,
+    /// The atom that owns this dep (for injection into correct eval context)
+    pub owner: AtomDigest,
+}
+
+impl<'a, S: LocalStorage> AtomResolver<'a, S> {
+    /// Creates a new AtomResolver for resolving dependencies.
+    ///
+    /// # Arguments
+    /// * `resolved_sets` - The resolved package sets from manifest processing
+    /// * `storage` - The storage backend for git operations
+    pub fn new(resolved_sets: &'a ResolvedSets<'a, S>) -> Self {
+        Self {
+            pool: Pool::default(),
+            discovered_candidates: RefCell::new(HashMap::new()),
+            manifest_cache: RefCell::new(HashMap::new()),
+            locally_available: RefCell::new(HashSet::default()),
+            resolved_sets,
+            transports: RefCell::new(HashMap::new()),
+            collected_nix_deps: RefCell::new(Vec::new()),
+        }
+    }
+}
+
+impl<'a, S: LocalStorage> Interner for AtomResolver<'a, S> {
+    fn display_solvable(&self, solvable: SolvableId) -> impl std::fmt::Display + '_ {
+        let solvable = self.pool.resolve_solvable(solvable);
+        let name = self.pool.resolve_package_name(solvable.name);
+        format!("{}@{}", name, solvable.record)
+    }
+
+    fn display_name(&self, name: NameId) -> impl std::fmt::Display + '_ {
+        self.pool.resolve_package_name(name).to_string()
+    }
+
+    fn display_version_set(&self, version_set: VersionSetId) -> impl std::fmt::Display + '_ {
+        self.pool.resolve_version_set(version_set).0.to_string()
+    }
+
+    fn display_string(&self, string_id: StringId) -> impl std::fmt::Display + '_ {
+        self.pool.resolve_string(string_id).to_string()
+    }
+
+    fn version_set_name(&self, version_set: VersionSetId) -> NameId {
+        self.pool.resolve_version_set_package_name(version_set)
+    }
+
+    fn solvable_name(&self, solvable: SolvableId) -> NameId {
+        self.pool.resolve_solvable(solvable).name
+    }
+
+    fn version_sets_in_union(
+        &self,
+        version_set_union: resolvo::VersionSetUnionId,
+    ) -> impl Iterator<Item = VersionSetId> {
+        self.pool.resolve_version_set_union(version_set_union)
+    }
+
+    fn resolve_condition(&self, condition: ConditionId) -> Condition {
+        self.pool.resolve_condition(condition).clone()
+    }
+}
+
+impl<'a, S: LocalStorage> DependencyProvider for AtomResolver<'a, S> {
+    /// Filter candidates by checking if version satisfies the version set
+    async fn filter_candidates(
+        &self,
+        candidates: &[SolvableId],
+        version_set: VersionSetId,
+        inverse: bool,
+    ) -> Vec<SolvableId> {
+        let vs = self.pool.resolve_version_set(version_set);
+        candidates
+            .iter()
+            .filter(|&&solvable_id| {
+                let solvable = self.pool.resolve_solvable(solvable_id);
+                let matches = vs.matches(&solvable.record.version);
+                if inverse { !matches } else { matches }
+            })
+            .copied()
+            .collect()
+    }
+
+    /// Get all candidate versions for a package
+    /// This uses CHEAP ref queries - no manifest fetching
+    async fn get_candidates(&self, name: NameId) -> Option<Candidates> {
+        let package_name = self.pool.resolve_package_name(name);
+
+        // Check if we've already discovered candidates for this package
+        if let Some(versions) = self.discovered_candidates.borrow().get(package_name) {
+            let candidate_ids: Vec<SolvableId> = versions.iter().map(|v| v.solvable_id).collect();
+
+            // Build hint_dependencies_available bitmap
+            let available_bitmap = self.build_availability_bitmap(&candidate_ids);
+
+            return Some(Candidates {
+                candidates: candidate_ids,
+                favored: None,
+                locked: None,
+                hint_dependencies_available: available_bitmap,
+                excluded: vec![],
+            });
+        }
+
+        // Need to discover candidates via cheap ref query
+        match self.discover_candidates_for_package(package_name).await {
+            Ok(candidates) => Some(candidates),
+            Err(e) => {
+                tracing::warn!(
+                    package = %package_name,
+                    error = %e,
+                    "failed to discover candidates"
+                );
+                None
+            },
+        }
+    }
+
+    /// Sort candidates by version descending (latest first)
+    async fn sort_candidates(
+        &self,
+        _solver: &resolvo::SolverCache<Self>,
+        solvables: &mut [SolvableId],
+    ) {
+        solvables.sort_by(|&a, &b| {
+            let va = &self.pool.resolve_solvable(a).record.version;
+            let vb = &self.pool.resolve_solvable(b).record.version;
+            vb.cmp(va) // Descending order: latest first
+        });
+    }
+
+    async fn get_dependencies(&self, solvable: SolvableId) -> Dependencies {
+        let solvable_data = self.pool.resolve_solvable(solvable);
+        let record = &solvable_data.record;
+        let version = &record.version;
+
+        // Check manifest cache first - use atom_id (digest) as key
+        let cache_key = (record.atom_id, version.clone());
+        if let Some(deps) = self.manifest_cache.borrow().get(&cache_key) {
+            return self.convert_deps_to_resolvo(deps);
+        }
+
+        // Need to fetch manifest - this is the expensive operation
+        // Use the stored package (AtomId<Root>) for fetching
+        match self
+            .fetch_and_parse_manifest(&record.package, version)
+            .await
+        {
+            Ok(deps) => {
+                // Cache for future use
+                self.manifest_cache
+                    .borrow_mut()
+                    .insert(cache_key, deps.clone());
+                self.convert_deps_to_resolvo(&deps)
+            },
+            Err(e) => {
+                let reason = self
+                    .pool
+                    .intern_string(format!("manifest fetch failed: {}", e));
+                Dependencies::Unknown(reason)
+            },
+        }
+    }
+}
+
+impl<'a, S: LocalStorage> AtomResolver<'a, S> {
+    /// Discover available versions for a package using cheap ref queries
+    /// This does NOT fetch manifests - only refs
+    async fn discover_candidates_for_package(
+        &self,
+        package: &AtomId<Root>,
+    ) -> Result<Candidates, BoxError> {
+        use crate::storage::QueryStore;
+
+        // Construct ref query pattern: refs/eka/atoms/<label>/*
+        let ref_pattern = format!(
+            "{}/*:{}/*",
+            format_args!("{}/{}", crate::ATOM_REFS.as_str(), package.label()),
+            format_args!("{}/{}", crate::ATOM_REFS.as_str(), package.label()),
+        );
+
+        // Get URL for this package's repository from resolved sets
+        let mirror_url = self.get_mirror_for_root(package.root())?;
+
+        // Cheap ref query via gix::Url (metadata only, no git objects)
+        let refs = {
+            let mut transports = self.transports.borrow_mut();
+            let transport = transports.get_mut(&mirror_url);
+            mirror_url.get_refs([ref_pattern.as_str()], transport)?
+        };
+
+        // Parse refs into versions
+        let mut versions = Vec::new();
+        let name_id = self.pool.intern_package_name(package.clone());
+
+        for r in refs {
+            if let Some((version, rev)) = self.parse_atom_ref(&r, package.label()) {
+                let record = AtomSolvableRecord {
+                    version: version.clone(),
+                    rev,
+                    manifest_cached: self.is_manifest_cached(&package.compute_hash(), &version),
+                    atom_id: package.compute_hash(),
+                    package: package.clone(),
+                };
+
+                let solvable_id = self.pool.intern_solvable(name_id, record.clone());
+
+                versions.push(DiscoveredVersion {
+                    version,
+                    solvable_id,
+                });
+            }
+        }
+
+        // Cache discovered versions
+        self.discovered_candidates
+            .borrow_mut()
+            .insert(package.clone(), versions.clone());
+
+        // Build result
+        let candidate_ids: Vec<_> = versions.iter().map(|v| v.solvable_id).collect();
+        let available_bitmap = self.build_availability_bitmap(&candidate_ids);
+
+        Ok(Candidates {
+            candidates: candidate_ids,
+            favored: None,
+            locked: None, // TODO: Check if version is already locked
+            hint_dependencies_available: available_bitmap,
+            excluded: vec![],
+        })
+    }
+
+    /// Parse an atom ref like "refs/eka/atoms/foo/1.2.3" into (Version, Rev)
+    fn parse_atom_ref(
+        &self,
+        r: &gix::protocol::handshake::Ref,
+        expected_label: &Label,
+    ) -> Option<(Version, GitDigest)> {
+        use bstr::ByteSlice;
+
+        let (name, ..) = r.unpack();
+        let id = to_id(r.clone());
+        let name_str = name.to_str().ok()?;
+
+        // Expected format: refs/eka/atoms/<label>/<version>
+        let prefix = format!("{}/{}/", crate::ATOM_REFS.as_str(), expected_label);
+        let version_str = name_str.strip_prefix(&prefix)?;
+
+        let version = Version::parse(version_str).ok()?;
+        let rev = match id {
+            gix::ObjectId::Sha1(bytes) => GitDigest::Sha1(bytes),
+        };
+
+        Some((version, rev))
+    }
+
+    /// Build availability bitmap based on which manifests are locally cached
+    fn build_availability_bitmap(&self, solvables: &[SolvableId]) -> HintDependenciesAvailable {
+        if solvables.is_empty() {
+            return HintDependenciesAvailable::None;
+        }
+
+        let locally_available = self.locally_available.borrow();
+        let all_available = solvables.iter().all(|id| locally_available.contains(id));
+        let any_available = solvables.iter().any(|id| locally_available.contains(id));
+
+        if all_available {
+            HintDependenciesAvailable::All
+        } else if any_available {
+            // Build specific bitmap of available solvable IDs
+            let available: Vec<SolvableId> = solvables
+                .iter()
+                .filter(|id| locally_available.contains(*id))
+                .copied()
+                .collect();
+            HintDependenciesAvailable::Some(available)
+        } else {
+            HintDependenciesAvailable::None
+        }
+    }
+
+    /// Get the mirror URL for a given root hash from resolved sets
+    fn get_mirror_for_root(&self, root: &Root) -> Result<gix::Url, BoxError> {
+        let root_digest = GitDigest::from(**root);
+        // Look up set details by root hash
+        if let Some(details) = self.resolved_sets.details().get(&root_digest) {
+            // Get the first mirror URL from the set
+            for mirror in &details.mirrors {
+                if let SetMirror::Url(url) = mirror {
+                    return Ok(url.clone());
+                }
+            }
+        }
+        Err(format!("No mirror found for root: {:?}", root).into())
+    }
+
+    /// Check if the manifest for a specific atom version is cached locally
+    fn is_manifest_cached(&self, atom_digest: &AtomDigest, version: &Version) -> bool {
+        let cache_key = (*atom_digest, version.clone());
+        self.manifest_cache.borrow().contains_key(&cache_key)
+    }
+
+    /// Resolve a set tag to its root hash
+    fn resolve_set_tag_to_root(&self, set_tag: &Tag) -> Option<Root> {
+        self.resolved_sets
+            .roots()
+            .get(&Either::Left(set_tag.clone()))
+            .copied()
+    }
+}
+
+impl<'a, S: LocalStorage> AtomResolver<'a, S> {
+    /// Fetch and parse manifest for a specific atom version
+    /// This is the EXPENSIVE operation - deferred until SAT solver needs deps
+    async fn fetch_and_parse_manifest(
+        &self,
+        package: &AtomId<Root>,
+        version: &Version,
+    ) -> Result<Vec<AtomDependency>, BoxError> {
+        tracing::debug!(
+            package = %package,
+            version = %version,
+            "fetching manifest (lazy)"
+        );
+
+        // Get mirror URL
+        let mirror_url = self.get_mirror_for_root(package.root())?;
+
+        // Fetch the atom commit
+        let _atom_ref = format!(
+            "{}/{}/{}",
+            crate::ATOM_REFS.as_str(),
+            package.label(),
+            version
+        );
+
+        // This fetches git objects - the expensive part
+        let cache_repo = crate::storage::git::cache::repo()?;
+        let local_repo = &cache_repo.to_thread_local();
+
+        // Get or create transport on-demand
+        let commit = {
+            use std::collections::hash_map::Entry;
+
+            use crate::storage::QueryStore;
+
+            let mut transports = self.transports.borrow_mut();
+            // If transport doesn't exist, create one via get_transport()
+            let transport = match transports.entry(mirror_url.clone()) {
+                Entry::Occupied(entry) => entry.into_mut(),
+                Entry::Vacant(entry) => {
+                    let new_transport = mirror_url.get_transport()?;
+                    entry.insert(new_transport)
+                },
+            };
+
+            let (root, remote) = local_repo.ensure_remote(&mirror_url, transport)?;
+            local_repo.resolve_atom_to_cache(
+                &mut (root, remote),
+                package.label(),
+                version,
+                transport,
+            )?
+        };
+
+        // Parse manifest from commit tree
+        let tree = commit.tree()?;
+        let manifest_entry = tree
+            .lookup_entry_by_path(crate::ATOM_MANIFEST_NAME.as_str())?
+            .ok_or("atom.toml not found in commit")?;
+
+        let blob = local_repo
+            .find_object(manifest_entry.object_id())?
+            .into_blob();
+        let manifest_str = std::str::from_utf8(&blob.data)?;
+        let manifest: ValidManifest = toml_edit::de::from_str(manifest_str)?;
+
+        // Extract dependencies
+        let mut deps = Vec::new();
+        for (set_tag, set_deps) in manifest.as_ref().deps().from() {
+            // Resolve set tag to root hash
+            match self.resolve_set_tag_to_root(set_tag) {
+                Some(set_root) => {
+                    for (label, version_req) in set_deps {
+                        deps.push(AtomDependency {
+                            target: AtomId::from((set_root, label.clone())),
+                            version_req: version_req.clone(),
+                        });
+                    }
+                },
+                None => {
+                    // Set tag not found in resolved_sets - this can happen when:
+                    // 1. A transitive dependency references a set not declared in the root manifest
+                    // 2. The set was removed from the manifest but deps still reference it
+                    tracing::warn!(
+                        package = %package,
+                        version = %version,
+                        set_tag = %set_tag,
+                        deps_count = set_deps.len(),
+                        "Skipping dependencies from unknown set tag - set not declared in manifest"
+                    );
+                    // We skip these deps rather than failing, allowing partial resolution
+                    // The resolver will fail later if these deps are actually required
+                },
+            }
+        }
+
+        // Collect nix deps from this transitive manifest
+        // The owner is computed from the package AtomId
+        let owner = package.compute_hash();
+        for (name, fetch) in manifest.as_ref().deps().direct().nix() {
+            self.collected_nix_deps.borrow_mut().push(CollectedNixDep {
+                name: name.clone(),
+                fetch: fetch.clone(),
+                owner,
+            });
+        }
+
+        // Mark this solvable as now having deps available
+        if let Some(versions) = self.discovered_candidates.borrow().get(package) {
+            for v in versions {
+                if &v.version == version {
+                    self.locally_available.borrow_mut().insert(v.solvable_id);
+                    break;
+                }
+            }
+        }
+
+        Ok(deps)
+    }
+
+    /// Convert parsed dependencies to resolvo's format.
+    /// Uses intern_package_name to ensure transitive deps are registered with the solver.
+    fn convert_deps_to_resolvo(&self, deps: &[AtomDependency]) -> Dependencies {
+        let requirements: Vec<ConditionalRequirement> = deps
+            .iter()
+            .map(|dep| {
+                // Use intern (not lookup) so transitive deps get registered
+                let name_id = self.pool.intern_package_name(dep.target.clone());
+                let version_set = SemverVersionSet(dep.version_req.clone());
+                let vs_id = self.pool.intern_version_set(name_id, version_set);
+
+                ConditionalRequirement {
+                    condition: None,
+                    requirement: Requirement::Single(vs_id),
+                }
+            })
+            .collect();
+
+        Dependencies::Known(KnownDependencies {
+            requirements,
+            constrains: vec![],
+        })
+    }
+}
+
+//================================================================================================
+// Resolution Entry Point
+//================================================================================================
+
+/// Result of a successful transitive resolution.
+#[derive(Debug)]
+pub struct ResolutionResult {
+    /// All resolved dependencies (direct and transitive).
+    pub deps: Vec<ResolvedDep>,
+    /// Nix deps collected from transitive atom manifests.
+    pub nix_deps: Vec<CollectedNixDep>,
+}
+
+/// A single resolved dependency with its transitive requirements.
+#[derive(Debug, Clone)]
+pub struct ResolvedDep {
+    /// The atom's label.
+    pub label: Label,
+    /// The resolved semantic version.
+    pub version: Version,
+    /// The set (repository root) this atom belongs to.
+    pub set: GitDigest,
+    /// The Git commit revision.
+    pub rev: GitDigest,
+    /// The computed atom digest.
+    pub atom_id: AtomDigest,
+    /// Dependencies of this atom, by their AtomDigest.
+    pub requires: Vec<AtomDigest>,
+    /// Whether this is a direct dependency (from root manifest).
+    pub direct: bool,
+}
+
+/// Errors that can occur during resolution.
+#[derive(Debug, thiserror::Error)]
+pub enum ResolutionError {
+    #[error("Resolution failed: {0}")]
+    Unsolvable(String),
+    #[error("Resolution cancelled")]
+    Cancelled,
+    #[error(transparent)]
+    Other(#[from] BoxError),
+}
+
+impl From<ResolvedDep> for crate::package::metadata::lock::AtomDep {
+    fn from(dep: ResolvedDep) -> Self {
+        crate::package::metadata::lock::AtomDep::new(
+            dep.label,
+            dep.version,
+            dep.set,
+            dep.rev,
+            dep.atom_id,
+            dep.requires,
+            dep.direct,
+        )
+    }
+}
+
+impl<'a, S: LocalStorage> AtomResolver<'a, S> {
+    /// Resolve transitive dependencies starting from the given manifest.
+    ///
+    /// This is the main entry point for SAT-based dependency resolution.
+    /// It takes the root manifest, discovers all transitive dependencies,
+    /// and returns a complete resolution with dependency graph information.
+    ///
+    /// # Arguments
+    /// * `manifest` - The root atom's manifest containing direct dependencies
+    ///
+    /// # Returns
+    /// A `ResolutionResult` containing all resolved deps (direct + transitive)
+    /// with their `requires` fields populated for graph reconstruction.
+    pub fn resolve(self, manifest: &ValidManifest) -> Result<ResolutionResult, ResolutionError> {
+        // Build root requirements from manifest's direct deps
+        let requirements = self.build_requirements_from_manifest(manifest)?;
+
+        if requirements.is_empty() {
+            // No dependencies to resolve
+            return Ok(ResolutionResult {
+                deps: Vec::new(),
+                nix_deps: Vec::new(),
+            });
+        }
+
+        // Create solver and problem - Solver takes ownership of the provider
+        let mut solver = Solver::new(self);
+        let problem = Problem::new().requirements(requirements);
+
+        // Run resolution
+        let solvables = match solver.solve(problem) {
+            Ok(solvables) => solvables,
+            Err(UnsolvableOrCancelled::Unsolvable(conflict)) => {
+                let error_msg = conflict.display_user_friendly(&solver).to_string();
+                return Err(ResolutionError::Unsolvable(error_msg));
+            },
+            Err(UnsolvableOrCancelled::Cancelled(_)) => {
+                return Err(ResolutionError::Cancelled);
+            },
+        };
+
+        // Extract results from the solver's provider
+        let provider = solver.provider();
+        let direct_deps = provider.collect_direct_dep_ids(manifest);
+        let deps = provider.extract_resolved_deps(&solvables, &direct_deps);
+        let nix_deps = provider.collected_nix_deps.borrow().clone();
+
+        Ok(ResolutionResult { deps, nix_deps })
+    }
+
+    /// Build ConditionalRequirements from the manifest's direct dependencies.
+    fn build_requirements_from_manifest(
+        &self,
+        manifest: &ValidManifest,
+    ) -> Result<Vec<ConditionalRequirement>, ResolutionError> {
+        let mut requirements = Vec::new();
+
+        for (set_tag, set_deps) in manifest.as_ref().deps().from() {
+            // Resolve set tag to root
+            let Some(set_root) = self.resolve_set_tag_to_root(set_tag) else {
+                tracing::warn!(
+                    set_tag = %set_tag,
+                    "Skipping dependencies from unknown set tag in root manifest"
+                );
+                continue;
+            };
+
+            for (label, version_req) in set_deps {
+                let atom_id = AtomId::from((set_root, label.clone()));
+                let name_id = self.pool.intern_package_name(atom_id);
+                let version_set = SemverVersionSet(version_req.clone());
+                let vs_id = self.pool.intern_version_set(name_id, version_set);
+
+                requirements.push(ConditionalRequirement {
+                    condition: None,
+                    requirement: Requirement::Single(vs_id),
+                });
+            }
+        }
+
+        Ok(requirements)
+    }
+
+    /// Collect the AtomIds of direct dependencies from the manifest.
+    fn collect_direct_dep_ids(&self, manifest: &ValidManifest) -> HashSet<AtomDigest> {
+        let mut direct = HashSet::default();
+
+        for (set_tag, set_deps) in manifest.as_ref().deps().from() {
+            if let Some(set_root) = self.resolve_set_tag_to_root(set_tag) {
+                for label in set_deps.keys() {
+                    let atom_id = AtomId::from((set_root, label.clone()));
+                    direct.insert(atom_id.compute_hash());
+                }
+            }
+        }
+
+        direct
+    }
+
+    /// Extract ResolvedDep structs from the solver's solution.
+    fn extract_resolved_deps(
+        &self,
+        solvables: &[SolvableId],
+        direct_deps: &HashSet<AtomDigest>,
+    ) -> Vec<ResolvedDep> {
+        solvables
+            .iter()
+            .map(|&solvable_id| {
+                let solvable = self.pool.resolve_solvable(solvable_id);
+                let record = &solvable.record;
+
+                // Get the requires from the manifest cache
+                let cache_key = (record.atom_id, record.version.clone());
+                let requires = self
+                    .manifest_cache
+                    .borrow()
+                    .get(&cache_key)
+                    .map(|deps| deps.iter().map(|d| d.target.compute_hash()).collect())
+                    .unwrap_or_default();
+
+                ResolvedDep {
+                    label: record.package.label().clone(),
+                    version: record.version.clone(),
+                    set: GitDigest::from(**record.package.root()),
+                    rev: record.rev,
+                    atom_id: record.atom_id,
+                    requires,
+                    direct: direct_deps.contains(&record.atom_id),
+                }
+            })
+            .collect()
+    }
+}
+
+//================================================================================================
+// Unit Tests
+//================================================================================================
+
+#[cfg(test)]
+mod tests {
+    use semver::Version;
+
+    use super::*;
+
+    // ========================================================================================
+    // SemverVersionSet Tests
+    // ========================================================================================
+
+    mod semver_version_set {
+        use super::*;
+
+        #[test]
+        fn parse_valid_requirements() {
+            assert!(SemverVersionSet::parse("^1.0").is_ok());
+            assert!(SemverVersionSet::parse(">=1.0.0, <2.0.0").is_ok());
+            assert!(SemverVersionSet::parse("~1.2.3").is_ok());
+            assert!(SemverVersionSet::parse("=1.0.0").is_ok());
+            assert!(SemverVersionSet::parse("*").is_ok());
+        }
+
+        #[test]
+        fn parse_invalid_requirements() {
+            assert!(SemverVersionSet::parse("invalid").is_err());
+            assert!(SemverVersionSet::parse(">>1.0").is_err());
+            assert!(SemverVersionSet::parse("1.0.0.0").is_err());
+        }
+
+        #[test]
+        fn matches_caret_requirement() {
+            let vs = SemverVersionSet::parse("^1.0.0").unwrap();
+
+            // Should match
+            assert!(vs.matches(&Version::parse("1.0.0").unwrap()));
+            assert!(vs.matches(&Version::parse("1.0.1").unwrap()));
+            assert!(vs.matches(&Version::parse("1.5.0").unwrap()));
+            assert!(vs.matches(&Version::parse("1.99.99").unwrap()));
+
+            // Should not match
+            assert!(!vs.matches(&Version::parse("0.9.9").unwrap()));
+            assert!(!vs.matches(&Version::parse("2.0.0").unwrap()));
+        }
+
+        #[test]
+        fn matches_tilde_requirement() {
+            let vs = SemverVersionSet::parse("~1.2.3").unwrap();
+
+            // Should match (patch-level changes only)
+            assert!(vs.matches(&Version::parse("1.2.3").unwrap()));
+            assert!(vs.matches(&Version::parse("1.2.4").unwrap()));
+            assert!(vs.matches(&Version::parse("1.2.99").unwrap()));
+
+            // Should not match
+            assert!(!vs.matches(&Version::parse("1.3.0").unwrap()));
+            assert!(!vs.matches(&Version::parse("1.1.0").unwrap()));
+        }
+
+        #[test]
+        fn matches_range_requirement() {
+            let vs = SemverVersionSet::parse(">=1.0.0, <2.0.0").unwrap();
+
+            assert!(vs.matches(&Version::parse("1.0.0").unwrap()));
+            assert!(vs.matches(&Version::parse("1.9.9").unwrap()));
+            assert!(!vs.matches(&Version::parse("0.9.9").unwrap()));
+            assert!(!vs.matches(&Version::parse("2.0.0").unwrap()));
+        }
+
+        #[test]
+        fn matches_star_requirement() {
+            let vs = SemverVersionSet::parse("*").unwrap();
+
+            assert!(vs.matches(&Version::parse("0.0.1").unwrap()));
+            assert!(vs.matches(&Version::parse("1.0.0").unwrap()));
+            assert!(vs.matches(&Version::parse("99.99.99").unwrap()));
+        }
+
+        #[test]
+        fn display_formats_correctly() {
+            let vs = SemverVersionSet::parse("^1.0.0").unwrap();
+            assert_eq!(format!("{}", vs), "^1.0.0");
+        }
+
+        #[test]
+        fn from_version_req_works() {
+            let req = VersionReq::parse(">=1.0").unwrap();
+            let vs: SemverVersionSet = req.clone().into();
+            assert_eq!(vs.inner(), &req);
+        }
+
+        #[test]
+        fn equality_and_hashing() {
+            use std::collections::HashSet;
+
+            let vs1 = SemverVersionSet::parse("^1.0").unwrap();
+            let vs2 = SemverVersionSet::parse("^1.0").unwrap();
+            let vs3 = SemverVersionSet::parse("^2.0").unwrap();
+
+            assert_eq!(vs1, vs2);
+            assert_ne!(vs1, vs3);
+
+            let mut set = HashSet::new();
+            set.insert(vs1.clone());
+            assert!(set.contains(&vs2));
+            assert!(!set.contains(&vs3));
+        }
+    }
+
+    // ========================================================================================
+    // AtomSolvableRecord Tests
+    // ========================================================================================
+    //
+    // NOTE: These tests require a proper AtomId<Root> which needs the git test harness.
+    // Uncomment when storage::git::test::init_repo_and_remote harness is integrated.
+    //
+    // mod atom_solvable_record {
+    //     use super::*;
+    //
+    //     fn make_test_atom_id() -> AtomId<Root> {
+    //         // Requires git harness - use init_repo_and_remote()
+    //         todo!("Implement with git test harness")
+    //     }
+    //
+    //     fn make_git_digest() -> GitDigest {
+    //         GitDigest::Sha1([0u8; 20])
+    //     }
+    //
+    //     #[test]
+    //     fn new_creates_uncached() {
+    //         let record = AtomSolvableRecord::new(
+    //             Version::parse("1.0.0").unwrap(),
+    //             make_git_digest(),
+    //             make_test_atom_id(),
+    //         );
+    //         assert!(!record.manifest_cached);
+    //     }
+    //
+    //     #[test]
+    //     fn with_cached_manifest_sets_flag() {
+    //         let record = AtomSolvableRecord::with_cached_manifest(
+    //             Version::parse("1.0.0").unwrap(),
+    //             make_git_digest(),
+    //             make_test_atom_id(),
+    //         );
+    //         assert!(record.manifest_cached);
+    //     }
+    //
+    //     #[test]
+    //     fn display_shows_version() {
+    //         let record = AtomSolvableRecord::new(
+    //             Version::parse("1.2.3").unwrap(),
+    //             make_git_digest(),
+    //             make_test_atom_id(),
+    //         );
+    //         assert_eq!(format!("{}", record), "1.2.3");
+    //     }
+    //
+    //     #[test]
+    //     fn ordering_by_version() {
+    //         let v1 = AtomSolvableRecord::new(
+    //             Version::parse("1.0.0").unwrap(),
+    //             make_git_digest(),
+    //             make_test_atom_id(),
+    //         );
+    //         let v2 = AtomSolvableRecord::new(
+    //             Version::parse("2.0.0").unwrap(),
+    //             make_git_digest(),
+    //             make_test_atom_id(),
+    //         );
+    //         let v1_5 = AtomSolvableRecord::new(
+    //             Version::parse("1.5.0").unwrap(),
+    //             make_git_digest(),
+    //             make_test_atom_id(),
+    //         );
+    //
+    //         assert!(v1 < v1_5);
+    //         assert!(v1_5 < v2);
+    //         assert!(v1 < v2);
+    //
+    //         let mut versions = vec![v2.clone(), v1.clone(), v1_5.clone()];
+    //         versions.sort();
+    //         assert_eq!(versions[0].version, Version::parse("1.0.0").unwrap());
+    //         assert_eq!(versions[1].version, Version::parse("1.5.0").unwrap());
+    //         assert_eq!(versions[2].version, Version::parse("2.0.0").unwrap());
+    //     }
+    //
+    //     #[test]
+    //     fn ordering_for_descending_sort() {
+    //         let v1 = AtomSolvableRecord::new(
+    //             Version::parse("1.0.0").unwrap(),
+    //             make_git_digest(),
+    //             make_test_atom_id(),
+    //         );
+    //         let v2 = AtomSolvableRecord::new(
+    //             Version::parse("2.0.0").unwrap(),
+    //             make_git_digest(),
+    //             make_test_atom_id(),
+    //         );
+    //
+    //         let mut versions = vec![v1.clone(), v2.clone()];
+    //         versions.sort_by(|a, b| b.cmp(a)); // Descending
+    //         assert_eq!(versions[0].version, Version::parse("2.0.0").unwrap());
+    //         assert_eq!(versions[1].version, Version::parse("1.0.0").unwrap());
+    //     }
+    // }
+
+    // ========================================================================================
+    // DiscoveryState Tests
+    // ========================================================================================
+
+    mod discovery_state {
+        use super::*;
+
+        fn make_test_digest(seed: u8) -> AtomDigest {
+            // AtomDigest uses Rfc4648HexLower base32 (0-9, a-v)
+            // Vary early in string for distinct decoded values
+            let s = match seed {
+                1 => "1000000000000000000000000000000000000000000000000000",
+                2 => "2000000000000000000000000000000000000000000000000000",
+                _ => "0000000000000000000000000000000000000000000000000000",
+            };
+            s.parse().unwrap()
+        }
+
+        #[test]
+        fn new_is_empty() {
+            let state = DiscoveryState::new();
+            assert!(state.discovered.is_empty());
+        }
+
+        #[test]
+        fn mark_pending_tracks_package() {
+            let mut state = DiscoveryState::new();
+            let digest = make_test_digest(1);
+
+            assert!(!state.is_discovered(&digest));
+            state.mark_pending(digest);
+            assert!(state.is_discovered(&digest));
+            assert_eq!(state.status(&digest), Some(&DiscoveryStatus::Pending));
+        }
+
+        #[test]
+        fn mark_completed_updates_status() {
+            let mut state = DiscoveryState::new();
+            let digest = make_test_digest(1);
+
+            state.mark_pending(digest);
+            state.mark_completed(digest, 5);
+
+            assert_eq!(state.status(&digest), Some(&DiscoveryStatus::Completed(5)));
+        }
+
+        #[test]
+        fn mark_failed_updates_status() {
+            let mut state = DiscoveryState::new();
+            let digest = make_test_digest(1);
+
+            state.mark_pending(digest);
+            state.mark_failed(digest, "network error".to_string());
+
+            assert_eq!(
+                state.status(&digest),
+                Some(&DiscoveryStatus::Failed("network error".to_string()))
+            );
+        }
+
+        #[test]
+        fn multiple_packages_tracked_independently() {
+            let mut state = DiscoveryState::new();
+            let digest1 = make_test_digest(1);
+            let digest2 = make_test_digest(2);
+
+            state.mark_pending(digest1);
+            state.mark_completed(digest2, 3);
+
+            assert_eq!(state.status(&digest1), Some(&DiscoveryStatus::Pending));
+            assert_eq!(state.status(&digest2), Some(&DiscoveryStatus::Completed(3)));
+        }
+    }
+
+    // ========================================================================================
+    // ManifestCache Tests
+    // ========================================================================================
+
+    mod manifest_cache {
+        use super::*;
+
+        fn make_test_digest(seed: u8) -> AtomDigest {
+            // AtomDigest uses Rfc4648HexLower base32 (0-9, a-v)
+            // Vary early in string for distinct decoded values
+            let s = match seed {
+                1 => "1000000000000000000000000000000000000000000000000000",
+                2 => "2000000000000000000000000000000000000000000000000000",
+                _ => "0000000000000000000000000000000000000000000000000000",
+            };
+            s.parse().unwrap()
+        }
+
+        #[test]
+        fn new_is_empty() {
+            let cache = ManifestCache::new();
+            let digest = make_test_digest(1);
+            let version = Version::parse("1.0.0").unwrap();
+
+            assert!(!cache.is_cached(&digest, &version));
+            assert!(cache.get(&digest, &version).is_none());
+        }
+
+        #[test]
+        fn insert_and_get() {
+            let mut cache = ManifestCache::new();
+            let digest = make_test_digest(1);
+            let version = Version::parse("1.0.0").unwrap();
+            let deps = vec![(make_test_digest(2), VersionReq::parse("^2.0").unwrap())];
+
+            cache.insert(digest, version.clone(), deps.clone());
+
+            assert!(cache.is_cached(&digest, &version));
+            let entry = cache.get(&digest, &version).unwrap();
+            assert_eq!(entry.dependencies.len(), 1);
+            assert_eq!(entry.dependencies[0].1, VersionReq::parse("^2.0").unwrap());
+        }
+
+        #[test]
+        fn different_versions_cached_separately() {
+            let mut cache = ManifestCache::new();
+            let digest = make_test_digest(1);
+            let v1 = Version::parse("1.0.0").unwrap();
+            let v2 = Version::parse("2.0.0").unwrap();
+
+            cache.insert(digest, v1.clone(), vec![]);
+
+            assert!(cache.is_cached(&digest, &v1));
+            assert!(!cache.is_cached(&digest, &v2));
+        }
+
+        #[test]
+        fn different_atoms_cached_separately() {
+            let mut cache = ManifestCache::new();
+            let digest1 = make_test_digest(1);
+            let digest2 = make_test_digest(2);
+            let version = Version::parse("1.0.0").unwrap();
+
+            cache.insert(digest1, version.clone(), vec![]);
+
+            assert!(cache.is_cached(&digest1, &version));
+            assert!(!cache.is_cached(&digest2, &version));
+        }
+
+        #[test]
+        fn empty_dependencies_is_valid() {
+            let mut cache = ManifestCache::new();
+            let digest = make_test_digest(1);
+            let version = Version::parse("1.0.0").unwrap();
+
+            cache.insert(digest, version.clone(), vec![]);
+
+            let entry = cache.get(&digest, &version).unwrap();
+            assert!(entry.dependencies.is_empty());
+        }
+    }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/atom/src/package/resolve/sat/test.rs b/crates/atom/src/package/resolve/sat/test.rs
new file mode 100644
index 0000000..a9188f5
--- /dev/null
+++ b/crates/atom/src/package/resolve/sat/test.rs
@@ -0,0 +1,361 @@
+//! Integration tests for SAT-based dependency resolution.
+//!
+//! These tests verify that the transitive dependency resolver correctly handles
+//! various dependency graph shapes and edge cases.
+
+use std::collections::HashMap;
+
+use gix::ThreadSafeRepository;
+
+use crate::package::metadata::manifest::ManifestWriter;
+use crate::package::publish::Builder;
+use crate::storage::{Init, QueryStore};
+use crate::test::harness::{MockAtom, commit_workdir, init_repo_and_remote, init_tracing};
+
+//================================================================================================
+// Tests
+//================================================================================================
+
+/// Test linear dependency chain: A → B → C
+///
+/// Creates three atoms where A depends on B and B depends on C.
+/// Verifies that resolution produces correct transitive deps.
+#[tokio::test]
+async fn test_linear_chain() -> Result<(), anyhow::Error> {
+    use crate::id::{Label, Tag};
+    use crate::package::metadata::manifest::SetMirror;
+    use crate::package::publish::Publish;
+    use crate::package::publish::git::GitPublisher;
+    use crate::uri::Uri;
+
+    init_tracing();
+
+    // Setup: Create repo with remote
+    let (repo_dir, remote_dir) = init_repo_and_remote()?;
+    let repo = ThreadSafeRepository::open(repo_dir.as_ref())?;
+    let local = repo.to_thread_local();
+
+    // Initialize ekala
+    local.ekala_init(None)?;
+
+    // Get remote and initialize it
+    let remote = local.find_remote("origin")?;
+    remote.get_refs(Some("refs/heads/*:refs/heads/*"), None)?;
+    remote.ekala_init(None)?;
+
+    // Get the remote URL for later use
+    let remote_url = format!("file://{}", remote_dir.path().display());
+
+    // Phase 1: Create all atoms WITHOUT dependencies first
+    let repo = local.into_sync();
+
+    let (_c_path, _c_oid) = repo.mock("atom-c", "1.0.0").await?;
+    tracing::info!("Created atom-c");
+
+    let (b_path, _b_oid) = repo.mock("atom-b", "1.0.0").await?;
+    tracing::info!("Created atom-b");
+
+    let (a_path, _a_oid) = repo.mock("atom-a", "1.0.0").await?;
+    tracing::info!("Created atom-a");
+
+    let mirrors = vec![SetMirror::Url(gix::url::parse(remote_url.as_str().into())?)];
+
+    // Phase 2: Add all dependencies to manifests (but don't publish yet)
+    // We first need to publish C so B can resolve its dependency on C
+    let local = repo.to_thread_local();
+    {
+        let progress = &tracing::info_span!("publish-c");
+        let (paths, publisher) = GitPublisher::new(&local, "origin", "HEAD", progress)?.build()?;
+        let label = Label::try_from("atom-c")?;
+        if let Some(path) = paths.as_ref().get_by_left(&label) {
+            publisher
+                .publish_atom(path, &HashMap::new())?
+                .expect("atoms failed to publish");
+        }
+        let mut errors = Vec::new();
+        publisher.await_pushes(&mut errors).await;
+        if !errors.is_empty() {
+            return Err(anyhow::anyhow!("publish C failed: {:?}", errors));
+        }
+        tracing::info!("Published atom-c");
+    }
+
+    // Add B -> C dependency
+    let repo = local.into_sync();
+    {
+        let b_dir = b_path.parent().expect("atom path has parent");
+        let mut writer = ManifestWriter::open_and_resolve(&repo, b_dir, true).await?;
+        let uri: Uri = format!("{}::atom-c@^1.0", remote_url).parse()?;
+        writer.add_uri(uri, Some(Tag::try_from("origin")?), mirrors.clone())?;
+        writer.write_atomic()?;
+        tracing::info!("Added atom-c dependency to atom-b");
+    }
+
+    // Commit B's changes and publish B
+    let local = repo.to_thread_local();
+    commit_workdir(&local, "add atom-c dep to atom-b")?;
+    {
+        let progress = &tracing::info_span!("publish-b");
+        let (paths, publisher) = GitPublisher::new(&local, "origin", "HEAD", progress)?.build()?;
+        let label = Label::try_from("atom-b")?;
+        if let Some(path) = paths.as_ref().get_by_left(&label) {
+            publisher
+                .publish_atom(path, &HashMap::new())?
+                .expect("atoms failed to publish");
+        }
+        let mut errors = Vec::new();
+        publisher.await_pushes(&mut errors).await;
+        if !errors.is_empty() {
+            return Err(anyhow::anyhow!("publish B failed: {:?}", errors));
+        }
+        tracing::info!("Published atom-b");
+    }
+
+    // Add A -> B dependency
+    let repo = local.into_sync();
+    {
+        let a_dir = a_path.parent().expect("atom path has parent");
+        let mut writer = ManifestWriter::open_and_resolve(&repo, a_dir, true).await?;
+        let uri: Uri = format!("{}::atom-b@^1.0", remote_url).parse()?;
+        writer.add_uri(uri, Some(Tag::try_from("origin")?), mirrors.clone())?;
+        writer.write_atomic()?;
+        tracing::info!("Added atom-b dependency to atom-a");
+    }
+
+    // WORKAROUND: Re-open to trigger transitive SAT resolution
+    // TODO: Fix add_uri to call synchronize internally
+    {
+        let a_dir = a_path.parent().expect("atom path has parent");
+        let writer = ManifestWriter::open_and_resolve(&repo, a_dir, false).await?;
+        writer.write_atomic()?;
+        tracing::info!("Ran full SAT resolution on atom-a");
+    }
+
+    // Verify lock file for atom-a has transitive deps
+    let a_dir = a_path.parent().expect("atom path has parent");
+    let lock_path = a_dir.join("atom.lock");
+    let lock_content = std::fs::read_to_string(&lock_path)?;
+    tracing::info!("Lock file contents:\n{}", lock_content);
+
+    let lock: crate::Lockfile = toml_edit::de::from_str(&lock_content)?;
+
+    let mut has_b = false;
+    let mut has_c = false;
+    for (_key, dep) in lock.deps.as_ref().iter() {
+        if let crate::package::metadata::lock::Dep::Atom(atom_dep) = dep {
+            if atom_dep.label().as_ref() == "atom-b" {
+                has_b = true;
+            }
+            if atom_dep.label().as_ref() == "atom-c" {
+                has_c = true;
+            }
+        }
+    }
+
+    assert!(has_b, "atom-b should be in lock file as direct dep");
+    assert!(has_c, "atom-c should be in lock file as transitive dep");
+
+    tracing::info!("Linear chain test passed!");
+    Ok(())
+}
+
+/// Test that unpublished local atoms are handled with pseudo-lock semantics.
+#[tokio::test]
+#[ignore = "Local atom pseudo-lock not yet implemented in new SAT resolver"]
+async fn test_local_unpublished_atom() -> Result<(), anyhow::Error> {
+    init_tracing();
+
+    let (repo_dir, _remote) = init_repo_and_remote()?;
+    let repo = ThreadSafeRepository::open(repo_dir.as_ref())?;
+    let local = repo.to_thread_local();
+
+    local.ekala_init(None)?;
+
+    let repo = local.into_sync();
+
+    // Create a local atom (not published)
+    let (_path, _oid) = repo.mock("local-atom", "1.0.0").await?;
+
+    // TODO: Create a root atom that depends on local-atom
+    // Verify that local-atom gets a pseudo-lock entry
+
+    Ok(())
+}
+
+/// Test diamond dependency pattern:
+/// ```text
+///     A
+///    / \
+///   B   C
+///    \ /
+///     D
+/// ```
+/// A depends on B and C, both B and C depend on D.
+/// Verifies that D appears exactly once in resolution.
+#[tokio::test]
+async fn test_diamond_dependency() -> Result<(), anyhow::Error> {
+    use crate::id::{Label, Tag};
+    use crate::package::metadata::manifest::SetMirror;
+    use crate::package::publish::Publish;
+    use crate::package::publish::git::GitPublisher;
+    use crate::uri::Uri;
+
+    init_tracing();
+
+    // Setup: Create repo with remote
+    let (repo_dir, remote_dir) = init_repo_and_remote()?;
+    let repo = ThreadSafeRepository::open(repo_dir.as_ref())?;
+    let local = repo.to_thread_local();
+
+    // Initialize ekala
+    local.ekala_init(None)?;
+
+    // Get remote and initialize it
+    let remote = local.find_remote("origin")?;
+    remote.get_refs(Some("refs/heads/*:refs/heads/*"), None)?;
+    remote.ekala_init(None)?;
+
+    let remote_url = format!("file://{}", remote_dir.path().display());
+
+    // Phase 1: Create all atoms WITHOUT dependencies
+    let repo = local.into_sync();
+
+    let (_d_path, _d_oid) = repo.mock("atom-d", "1.0.0").await?;
+    tracing::info!("Created atom-d (shared leaf)");
+
+    let (b_path, _b_oid) = repo.mock("atom-b", "1.0.0").await?;
+    tracing::info!("Created atom-b");
+
+    let (c_path, _c_oid) = repo.mock("atom-c", "1.0.0").await?;
+    tracing::info!("Created atom-c");
+
+    let (a_path, _a_oid) = repo.mock("atom-a", "1.0.0").await?;
+    tracing::info!("Created atom-a");
+
+    let mirrors = vec![SetMirror::Url(gix::url::parse(remote_url.as_str().into())?)];
+
+    // Publish D first (no dependencies)
+    let local = repo.to_thread_local();
+    {
+        let progress = &tracing::info_span!("publish-d");
+        let (paths, publisher) = GitPublisher::new(&local, "origin", "HEAD", progress)?.build()?;
+        let label = Label::try_from("atom-d")?;
+        if let Some(path) = paths.as_ref().get_by_left(&label) {
+            publisher
+                .publish_atom(path, &HashMap::new())?
+                .expect("atoms failed to publish");
+        }
+        let mut errors = Vec::new();
+        publisher.await_pushes(&mut errors).await;
+        if !errors.is_empty() {
+            return Err(anyhow::anyhow!("publish D failed: {:?}", errors));
+        }
+        tracing::info!("Published atom-d");
+    }
+
+    // Add B -> D dependency
+    let repo = local.into_sync();
+    {
+        let b_dir = b_path.parent().expect("atom path has parent");
+        let mut writer = ManifestWriter::open_and_resolve(&repo, b_dir, true).await?;
+        let uri: Uri = format!("{}::atom-d@^1.0", remote_url).parse()?;
+        writer.add_uri(uri, Some(Tag::try_from("origin")?), mirrors.clone())?;
+        writer.write_atomic()?;
+        tracing::info!("Added atom-d dependency to atom-b");
+    }
+
+    // Add C -> D dependency
+    {
+        let c_dir = c_path.parent().expect("atom path has parent");
+        let mut writer = ManifestWriter::open_and_resolve(&repo, c_dir, true).await?;
+        let uri: Uri = format!("{}::atom-d@^1.0", remote_url).parse()?;
+        writer.add_uri(uri, Some(Tag::try_from("origin")?), mirrors.clone())?;
+        writer.write_atomic()?;
+        tracing::info!("Added atom-d dependency to atom-c");
+    }
+
+    // Commit B and C changes, then publish them
+    let local = repo.to_thread_local();
+    commit_workdir(&local, "add atom-d deps to atom-b and atom-c")?;
+    {
+        let progress = &tracing::info_span!("publish-bc");
+        let (paths, publisher) = GitPublisher::new(&local, "origin", "HEAD", progress)?.build()?;
+        for label_str in ["atom-b", "atom-c"] {
+            let label = Label::try_from(label_str)?;
+            if let Some(path) = paths.as_ref().get_by_left(&label) {
+                publisher
+                    .publish_atom(path, &HashMap::new())?
+                    .expect("atoms failed to publish");
+            }
+        }
+        let mut errors = Vec::new();
+        publisher.await_pushes(&mut errors).await;
+        if !errors.is_empty() {
+            return Err(anyhow::anyhow!("publish B/C failed: {:?}", errors));
+        }
+        tracing::info!("Published atom-b and atom-c");
+    }
+
+    // Add A -> B, C dependencies
+    let repo = local.into_sync();
+    {
+        let a_dir = a_path.parent().expect("atom path has parent");
+        let mut writer = ManifestWriter::open_and_resolve(&repo, a_dir, true).await?;
+
+        let uri_b: Uri = format!("{}::atom-b@^1.0", remote_url).parse()?;
+        writer.add_uri(uri_b, Some(Tag::try_from("origin")?), mirrors.clone())?;
+
+        let uri_c: Uri = format!("{}::atom-c@^1.0", remote_url).parse()?;
+        writer.add_uri(uri_c, Some(Tag::try_from("origin")?), mirrors.clone())?;
+
+        writer.write_atomic()?;
+        tracing::info!("Added atom-b and atom-c dependencies to atom-a");
+    }
+
+    // WORKAROUND: Re-open to trigger transitive SAT resolution
+    // TODO: Fix add_uri to call synchronize internally
+    {
+        let a_dir = a_path.parent().expect("atom path has parent");
+        let writer = ManifestWriter::open_and_resolve(&repo, a_dir, false).await?;
+        writer.write_atomic()?;
+        tracing::info!("Ran full SAT resolution on atom-a");
+    }
+
+    // Verify lock file
+    let a_dir = a_path.parent().expect("atom path has parent");
+    let lock_path = a_dir.join("atom.lock");
+    let lock_content = std::fs::read_to_string(&lock_path)?;
+    tracing::info!("Lock file contents:\n{}", lock_content);
+
+    let lock: crate::Lockfile = toml_edit::de::from_str(&lock_content)?;
+
+    let mut d_count = 0;
+    let mut has_b = false;
+    let mut has_c = false;
+
+    for (_key, dep) in lock.deps.as_ref().iter() {
+        if let crate::package::metadata::lock::Dep::Atom(atom_dep) = dep {
+            let label = atom_dep.label().as_ref();
+            if label == "atom-d" {
+                d_count += 1;
+            }
+            if label == "atom-b" {
+                has_b = true;
+            }
+            if label == "atom-c" {
+                has_c = true;
+            }
+        }
+    }
+
+    assert_eq!(
+        d_count, 1,
+        "atom-d should appear exactly once in lock file (diamond dedup), found {} times",
+        d_count
+    );
+    assert!(has_b, "atom-b should be in lock file");
+    assert!(has_c, "atom-c should be in lock file");
+
+    tracing::info!("Diamond dependency test passed!");
+    Ok(())
+}
diff --git a/crates/atom/src/package/sets/mod.rs b/crates/atom/src/package/sets/mod.rs
index 9e43c3a..fae74bc 100644
--- a/crates/atom/src/package/sets/mod.rs
+++ b/crates/atom/src/package/sets/mod.rs
@@ -128,8 +128,4 @@ impl<Id, R> ResolvedAtom<Id, R> {
     pub(super) fn unpack(&self) -> &UnpackedRef<Id, R> {
         &self.unpacked
     }
-
-    pub(super) fn remotes(&self) -> &BTreeSet<gix::Url> {
-        &self.remotes
-    }
 }
diff --git a/crates/atom/src/storage.rs b/crates/atom/src/storage.rs
index 78d5e3d..5140338 100644
--- a/crates/atom/src/storage.rs
+++ b/crates/atom/src/storage.rs
@@ -82,6 +82,7 @@
 //! that need to be imported explicitly. The `UnpackedRef` fields are not publicly accessible.
 
 use std::collections::HashMap;
+use std::fmt::Debug;
 use std::path::{Path, PathBuf};
 
 use bstr::BStr;
@@ -154,7 +155,7 @@ pub struct LocalStoragePath(PathBuf);
 
 /// A trait representing a type which implements the full resonsibilities of a local ekala storage
 /// layer
-pub trait LocalStorage: Init + NormalizeStorePath + Sync + Send {}
+pub trait LocalStorage: Init + NormalizeStorePath + Sync + Send + Debug {}
 
 /// A trait representing the methods required to initialize an Ekala store.
 pub trait Init {
@@ -179,6 +180,7 @@ pub trait EkalaStorage {
     type Error: From<std::path::StripPrefixError>
         + From<toml_edit::de::Error>
         + From<std::io::Error>
+        + From<crate::package::metadata::DocError>
         + std::error::Error
         + std::marker::Send
         + std::marker::Sync
@@ -190,11 +192,10 @@ pub trait EkalaStorage {
         let path = self
             .ekala_root_dir()?
             .join(crate::EKALA_MANIFEST_NAME.as_str());
-        let ekala: EkalaManifest =
-            toml_edit::de::from_str(&std::fs::read_to_string(&path).inspect_err(
-                |_| tracing::warn!(path = %path.display(), "could not locate ekala.toml"),
-            )?)?;
-        Ok(ekala)
+        EkalaManifest::open_filesystem(&path).map_err(|e| {
+            tracing::warn!(path = %path.display(), error = %e, "could not open ekala.toml");
+            Self::Error::from(e)
+        })
     }
     /// returns the corrent working directory inside the store, failing if outside
     fn cwd(&self) -> Result<impl AsRef<Path>, Self::Error>;
@@ -555,11 +556,126 @@ pub trait UnpackRef {
     fn find_root_ref(&self) -> Option<Self::Root>;
 }
 
+/// A trait for caching and retrieving atoms from remote sources.
+///
+/// This trait provides a unified interface for different caching backends
+/// (e.g., git, HTTP, S3) to store and retrieve atoms from remote sources.
+/// The cache should handle deduplication, versioning, and efficient retrieval.
+///
+/// ## Key Features
+///
+/// - **Remote Setup**: Ensure the cache knows how to reach a remote source
+/// - **Commit Resolution**: Fetch or locate the commit for a specific atom version
+/// - **Materialization**: Extract cached commits into temporary working directories
+/// - **High-level Convenience**: Combined operations for common use cases
+///
+/// ## Use Cases
+///
+/// - **Atom Evaluation**: Retrieve atoms for evaluation in sandboxes
+/// - **Dependency Caching**: Cache remote atoms to avoid repeated downloads
+/// - **Offline Workflows**: Materialize cached atoms without network access
+/// - **Verification**: Access commit metadata for integrity checks
+pub trait RemoteAtomCache {
+    /// The error type returned by cache operations.
+    type Error: std::fmt::Display + std::error::Error + Send + Sync + 'static;
+    /// The type representing a handle to a configured remote.
+    type RemoteHandle;
+    /// The type repesenting the transport to utilize for the connection.
+    type Transport: Send;
+    /// The type repesenting the atom in the storage backend.
+    type Atom;
+
+    /// Ensure the cache backend knows how to reach the given remote URL.
+    ///
+    /// This method sets up any necessary configuration or connections for
+    /// subsequent operations on this remote. The returned handle can be reused
+    /// for multiple operations without re-establishing connections.
+    ///
+    /// # Arguments
+    /// * `url` - The remote repository URL
+    /// * `transport` - Mutable reference to the transport for remote operations
+    ///
+    /// # Returns
+    /// A handle for further operations on this remote, or an error if setup fails.
+    fn ensure_remote(
+        &self,
+        url: &gix::Url,
+        transport: &mut Self::Transport,
+    ) -> Result<Self::RemoteHandle, Self::Error>;
+
+    /// Resolve the commit ID for a specific atom version from the remote.
+    ///
+    /// This method fetches or locates the commit corresponding to the given
+    /// atom label and version. The commit should be cached locally if not already present.
+    ///
+    /// # Arguments
+    /// * `remote` - Handle to the configured remote (from `ensure_remote`)
+    /// * `label` - The atom label (e.g., "mylib")
+    /// * `version` - The semantic version to retrieve
+    /// * `transport` - Mutable reference to the transport for remote operations
+    ///
+    /// # Returns
+    /// The ObjectId of the commit, or an error if resolution fails.
+    fn resolve_atom_to_cache(
+        &self,
+        remote: &mut Self::RemoteHandle,
+        label: &Label,
+        version: &Version,
+        transport: &mut Self::Transport,
+    ) -> Result<Self::Atom, Self::Error>;
+
+    /// Materialize a cached atom into a temporary working directory.
+    ///
+    /// This method extracts the tree contents of the given commit into a
+    /// temporary directory, preserving file permissions, symlinks, and structure.
+    ///
+    /// # Arguments
+    /// * `atom` - The atom to materialize
+    ///
+    /// # Returns
+    /// A TempDir containing the extracted files, or an error if materialization fails.
+    fn materialize_from_cache(
+        &self,
+        atom: Self::Atom,
+        to_dir: impl AsRef<Path>,
+    ) -> Result<tempfile::TempDir, Self::Error>;
+
+    /// High-level convenience method to retrieve an atom as a temporary directory.
+    ///
+    /// This method combines `ensure_remote`, `resolve_atom_to_cache`, and `materialize_from_cache`
+    /// into a single operation for common use cases.
+    ///
+    /// # Arguments
+    /// * `url` - The remote repository URL
+    /// * `label` - The atom label (e.g., "mylib")
+    /// * `version` - The semantic version to retrieve
+    /// * `transport` - Mutable reference to the transport for remote operations
+    ///
+    /// # Returns
+    /// A TempDir containing the atom's files, or an error if retrieval fails.
+    fn cache_and_materialize_atom(
+        &self,
+        url: &gix::Url,
+        label: &Label,
+        version: &Version,
+        transport: &mut Self::Transport,
+        material_base: impl AsRef<Path>,
+    ) -> Result<tempfile::TempDir, Self::Error> {
+        let mut remote = self.ensure_remote(url, transport)?;
+        let commit = self.resolve_atom_to_cache(&mut remote, label, version, transport)?;
+        self.materialize_from_cache(commit, material_base)
+    }
+
+    /// Take's an arbitrary filepath, determines if it points at a valid atom, and if so, imports it
+    /// into the global atom store.
+    fn path_to_cache(&self, path: impl AsRef<Path>) -> Result<(Version, Self::Atom), Self::Error>;
+}
+
 //================================================================================================
 // Impls
 //================================================================================================
 
-impl<T: Init + NormalizeStorePath + Send + Sync> LocalStorage for T {}
+impl<T: Init + NormalizeStorePath + Send + Sync + Debug> LocalStorage for T {}
 
 impl LocalStoragePath {
     /// verifies a path is actually contained in an ekala storage layer before allowing construction
diff --git a/crates/atom/src/storage/git.rs b/crates/atom/src/storage/git.rs
index 47dd4a8..63805ee 100644
--- a/crates/atom/src/storage/git.rs
+++ b/crates/atom/src/storage/git.rs
@@ -40,7 +40,8 @@ use std::path::{Path, PathBuf};
 use std::sync::OnceLock;
 use std::{fs, io};
 
-use bstr::BStr;
+use bstr::{BStr, ByteSlice};
+pub use cache::{NIX_ENTRY_KEY, NIX_IMPORT_FILE, repo as cache_repo};
 use gix::discover::upwards::Options;
 use gix::protocol::handshake::Ref;
 use gix::protocol::transport::client::Transport;
@@ -57,6 +58,8 @@ use crate::package::AtomError;
 use crate::package::metadata::{DocError, EkalaManifest, GitDigest};
 use crate::{AtomId, Label};
 
+pub(crate) mod cache;
+
 #[cfg(test)]
 pub(crate) mod test;
 
@@ -64,14 +67,12 @@ pub(crate) mod test;
 // Constants
 //================================================================================================
 
-pub(super) const V1_ROOT: &str = "refs/ekala/init";
+pub(crate) const V1_ROOT: &str = "refs/ekala/init";
 
 //================================================================================================
 // Statics
 //================================================================================================
 
-pub(crate) static LOCK_ROOT: Root = Root(ObjectId::Sha1(crate::EKA_ROOT_COMMIT_HASH));
-
 static DEFAULT_REMOTE: OnceLock<Cow<str>> = OnceLock::new();
 /// Provide a lazily instantiated static reference to the git repository.
 static REPO: OnceLock<Option<ThreadSafeRepository>> = OnceLock::new();
@@ -185,6 +186,9 @@ pub enum Error {
     /// A transparent wrapper for a [`DocError`]
     #[error(transparent)]
     Doc(#[from] DocError),
+    #[error(transparent)]
+    /// A transparent wrapper for a [`cache::Error`]
+    AtomStore(#[from] cache::Error),
     /// A generic boxed error variant
     #[error(transparent)]
     Generic(Box<dyn std::error::Error + Send + Sync>),
@@ -309,10 +313,11 @@ impl Init for gix::Repository {
         let manifest_filename = crate::EKALA_MANIFEST_NAME.as_str();
         let manifest_path = workdir.join(manifest_filename);
 
-        let content = if let Ok(content) = fs::read_to_string(&manifest_path) {
-            let _manifest: EkalaManifest =
-                toml_edit::de::from_str(&content).map_err(|e| Error::Generic(Box::new(e)))?;
-            content
+        let content = if manifest_path.exists() {
+            // Validate by opening - this enforces all invariants
+            let _manifest = EkalaManifest::open_filesystem(&manifest_path)
+                .map_err(|e| Error::Generic(Box::new(e)))?;
+            fs::read_to_string(&manifest_path)?
         } else {
             let manifest = EkalaManifest::new();
             let content = toml_edit::ser::to_string_pretty(&manifest)?;
@@ -575,18 +580,21 @@ impl<'repo> Init for gix::Remote<'repo> {
             .to_string();
 
         // FIXME: use gix for push once it supports it
-        run_git_command(&[
-            "-C",
-            repo.git_dir().to_string_lossy().as_ref(),
-            "push",
-            remote,
-            format!("{root_ref}:{root_ref}").as_str(),
-        ])?;
+        run_git_command(
+            repo.git_dir(),
+            &["push", remote, format!("{root_ref}:{root_ref}").as_str()],
+        )?;
         tracing::info!(ekala.remote = %remote, ekala.root = %*root, "Successfully initialized");
         Ok(())
     }
 }
 
+/// query the root of a gix::Url
+pub fn query_root(url: &gix::Url) -> Result<Root, Error> {
+    let q = format!("{}:{}", V1_ROOT, V1_ROOT);
+    Ok(Root(to_id(url.get_ref(q.as_str(), None)?)))
+}
+
 impl EkalaStorage for Repository {
     type Error = Error;
 
@@ -690,35 +698,48 @@ impl super::QueryStore for gix::Url {
         };
 
         let config = gix::config::File::from_globals()?;
-        let (mut cascade, _, prompt_opts) = gix::config::credential_helpers(
-            self.to_owned(),
-            &config,
-            true,
-            gix::config::section::is_trusted,
-            Environment {
-                xdg_config_home: Permission::Allow,
-                home: Permission::Allow,
-                http_transport: Permission::Allow,
-                identity: Permission::Allow,
-                objects: Permission::Allow,
-                git_prefix: Permission::Allow,
-                ssh_prefix: Permission::Allow,
-            },
-            false,
-        )?;
 
-        let authenticate = Box::new(move |action| cascade.invoke(action, prompt_opts.clone()));
-
-        let mut handshake = gix::protocol::fetch::handshake(
-            &mut *transport,
-            authenticate,
-            Vec::new(),
-            &mut prodash::progress::Discard,
-        )
-        .map_err(|e| {
-            tracing::error!(url = %self, "couldn't establish a handshake with the remote");
-            Box::new(e)
-        })?;
+        let shake_hands = |transport: &mut Box<dyn Transport + Send>| {
+            let (mut cascade, _, prompt_opts) = gix::config::credential_helpers(
+                self.to_owned(),
+                &config,
+                true,
+                gix::config::section::is_trusted,
+                Environment {
+                    xdg_config_home: Permission::Allow,
+                    home: Permission::Allow,
+                    http_transport: Permission::Allow,
+                    identity: Permission::Allow,
+                    objects: Permission::Allow,
+                    git_prefix: Permission::Allow,
+                    ssh_prefix: Permission::Allow,
+                },
+                false,
+            )?;
+            let authenticate = Box::new(move |action| cascade.invoke(action, prompt_opts.clone()));
+
+            gix::protocol::fetch::handshake(
+                &mut *transport,
+                authenticate,
+                Vec::new(),
+                &mut prodash::progress::Discard,
+            )
+            .map_err(Box::new)
+            .map_err(Error::Handshake)
+        };
+
+        let mut handshake = shake_hands(transport)
+            .or_else(|e| {
+                if !transport.connection_persists_across_multiple_requests() {
+                    let mut transport = self.get_transport()?;
+                    shake_hands(&mut transport)
+                } else {
+                    Err(e)
+                }
+            })
+            .inspect_err(|_| {
+                tracing::error!(url = %self, "couldn't establish a handshake with the remote");
+            })?;
 
         tracing::debug!(?targets, url = %self, "checking remote for refs");
         use gix::refspec::parse::Operation;
@@ -759,10 +780,20 @@ impl super::QueryStore for gix::Url {
         Spec: AsRef<BStr> + std::fmt::Debug,
     {
         let name = target.as_ref().to_string();
+        let (name, _) = name.split_once(':').unwrap_or(("", ""));
         self.get_refs(Some(target), transport).and_then(|r| {
-            r.into_iter()
-                .next()
-                .ok_or(Error::NoRef(name, self.to_string()))
+            let orig = r.clone();
+            let names = r.iter().map(|r| {
+                let (n, ..) = r.unpack();
+                n
+            });
+            let res = resolve_partial_name(name, names);
+            orig.into_iter()
+                .find(|r| {
+                    let (n, ..) = r.unpack();
+                    Some(n) == res
+                })
+                .ok_or(Error::NoRef(name.into(), self.to_string()))
         })
     }
 
@@ -773,6 +804,47 @@ impl super::QueryStore for gix::Url {
     }
 }
 
+/// Resolves a partial ref name to a full ref name using the same precedence as gix.
+/// Returns the first matching ref from available_refs, or None.
+fn resolve_partial_name<'a>(
+    partial_name: &str,
+    available_refs: impl IntoIterator<Item = &'a BStr>,
+) -> Option<&'a BStr> {
+    use bstr::{BStr, BString};
+    let available: std::collections::HashSet<_> = available_refs.into_iter().collect();
+    let partial_name = BStr::new(partial_name);
+
+    // If it already looks like a full ref name, check for exact match
+    if partial_name.starts_with(b"refs/") {
+        return available.get(partial_name).copied();
+    }
+
+    // Use the exact same expansion order as gix-refspec/src/spec.rs:236
+    let expansions = [
+        ("", false),              // 0: <name>
+        ("refs/", false),         // 1: refs/<name>
+        ("refs/tags/", false),    // 2: refs/tags/<name>
+        ("refs/heads/", false),   // 3: refs/heads/<name>
+        ("refs/remotes/", false), // 4: refs/remotes/<name>
+        ("refs/remotes/", true),  // 5: refs/remotes/<name>/HEAD
+    ];
+
+    for (base, append_head) in expansions {
+        let mut candidate = BString::from(base);
+        candidate.extend_from_slice(partial_name);
+        if append_head {
+            candidate.extend_from_slice("/HEAD".as_bytes());
+        }
+
+        if available.contains(candidate.as_bstr()) {
+            // Return the original ref name from available_refs
+            return available.into_iter().find(|&r| r == candidate.as_bstr());
+        }
+    }
+
+    None
+}
+
 impl<'repo> super::QueryStore for gix::Remote<'repo> {
     type Error = Error;
     type Ref = Ref;
@@ -820,8 +892,6 @@ impl<'repo> super::QueryStore for gix::Remote<'repo> {
         use tracing::level_filters::LevelFilter;
 
         let tree = Root::new();
-        let sync_progress = tree.add_child("sync");
-        let init_progress = tree.add_child("init");
         let _ = if LevelFilter::current() > LevelFilter::WARN {
             Some(setup_line_renderer(&tree))
         } else {
@@ -834,22 +904,39 @@ impl<'repo> super::QueryStore for gix::Remote<'repo> {
             .replace_refspecs(references, Direction::Fetch)
             .map_err(Box::new)?;
 
-        let transport = if let Some(transport) = transport {
-            transport
-        } else {
-            &mut remote.get_transport()?
-        };
+        let fetch = |transport: Option<&mut Self::Transport>| {
+            let sync_progress = tree.add_child("sync");
+            let init_progress = tree.add_child("init");
+
+            let transport = if let Some(transport) = transport {
+                transport
+            } else {
+                &mut remote.get_transport()?
+            };
 
-        let client = remote.to_connection_with_transport(transport);
+            remote
+                .to_connection_with_transport(transport)
+                .prepare_fetch(sync_progress, Options::default())
+                .map_err(Box::new)
+                .map_err(Error::Refs)
+                .and_then(|p| {
+                    Ok(p.with_write_packed_refs_only(true)
+                        .receive(init_progress, &AtomicBool::new(false))
+                        .map_err(Box::new)?)
+                })
+        };
 
-        let query = client
-            .prepare_fetch(sync_progress, Options::default())
-            .map_err(Box::new)?;
+        let supports_multiple = transport
+            .as_ref()
+            .is_some_and(|t| t.connection_persists_across_multiple_requests());
 
-        let outcome = query
-            .with_write_packed_refs_only(true)
-            .receive(init_progress, &AtomicBool::new(false))
-            .map_err(Box::new)?;
+        let outcome = fetch(transport).or_else(|e| {
+            if !supports_multiple {
+                fetch(None)
+            } else {
+                Err(e)
+            }
+        })?;
 
         Ok(outcome.ref_map.remote_refs)
     }
@@ -865,7 +952,10 @@ impl<'repo> super::QueryStore for gix::Remote<'repo> {
         let name = target.as_ref().to_string();
         self.get_refs(Some(target), transport).and_then(|r| {
             r.into_iter()
-                .next()
+                .find(|r| {
+                    let (n, ..) = r.unpack();
+                    name.contains(n.to_string().as_str())
+                })
                 .ok_or(Error::NoRef(name, self.symbol().to_owned()))
         })
     }
@@ -968,9 +1058,13 @@ pub fn repo() -> Result<Option<&'static ThreadSafeRepository>, Box<gix::discover
 ///
 /// Note: This function is a temporary workaround for operations not yet implemented in `gix`.
 /// It should be removed once `gix` supports all necessary functionality (e.g., push).
-pub fn run_git_command(args: &[&str]) -> io::Result<Vec<u8>> {
+pub fn run_git_command(git_dir: &Path, args: &[&str]) -> io::Result<Vec<u8>> {
     use std::process::Command;
-    let output = Command::new("git").args(args).output()?;
+    let output = Command::new("git")
+        .arg("-C")
+        .arg(git_dir)
+        .args(args)
+        .output()?;
 
     if output.status.success() {
         Ok(output.stdout)
diff --git a/crates/atom/src/storage/git/cache.rs b/crates/atom/src/storage/git/cache.rs
new file mode 100644
index 0000000..fa020e6
--- /dev/null
+++ b/crates/atom/src/storage/git/cache.rs
@@ -0,0 +1,389 @@
+use std::collections::HashMap;
+use std::os::unix::fs::MetadataExt;
+use std::path::{Path, PathBuf, StripPrefixError};
+use std::sync::OnceLock;
+
+use bstr::ByteSlice;
+use gix::create::{Kind, Options};
+use gix::objs::tree::EntryKind;
+use gix::protocol::transport::client::Transport;
+use gix::{Commit, ObjectId, Remote, Repository, ThreadSafeRepository};
+use package::publish::git;
+use semver::{BuildMetadata, Prerelease, Version};
+use storage::git::NULLROOT;
+use storage::{QueryStore, RemoteAtomCache};
+
+use crate::package::AtomError;
+use crate::storage::git::Root;
+use crate::{AtomId, Compute, DocError, Genesis, Label, ValidManifest, package, storage};
+
+/// The filename of the file used to run nix import logic
+pub const NIX_IMPORT_FILE: &str = "atom.nix";
+/// The entrypoint attribute to evaluate inside the atom
+pub const NIX_ENTRY_KEY: &str = "main";
+
+static CACHE_REPO: OnceLock<Option<ThreadSafeRepository>> = OnceLock::new();
+
+#[derive(thiserror::Error, Debug)]
+pub enum Error {
+    #[error("couldn't open cache repository: {0}")]
+    Repo(PathBuf),
+    #[error("the path passed is not an atom: {0}")]
+    NotAnAtom(PathBuf),
+    #[error(transparent)]
+    Init(#[from] Box<gix::init::Error>),
+    #[error(transparent)]
+    RemoteInit(#[from] gix::remote::init::Error),
+    #[error(transparent)]
+    GitStorage(#[from] Box<super::Error>),
+    #[error(transparent)]
+    GitConfig(#[from] gix::config::file::init::from_paths::Error),
+    #[error(transparent)]
+    SaveRemote(#[from] Box<gix::remote::save::AsError>),
+    #[error(transparent)]
+    GitTree(#[from] gix::object::commit::Error),
+    #[error(transparent)]
+    Traverse(#[from] gix::traverse::tree::breadthfirst::Error),
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+    #[error(transparent)]
+    Find(#[from] gix::object::find::existing::Error),
+    #[error(transparent)]
+    TryObject(#[from] gix::object::try_into::Error),
+    #[error(transparent)]
+    Utf8(#[from] std::str::Utf8Error),
+    #[error(transparent)]
+    RepoWrite(#[from] gix::object::write::Error),
+    #[error(transparent)]
+    Ignore(#[from] ignore::Error),
+    #[error(transparent)]
+    WriteAtom(#[from] Box<package::publish::error::git::Error>),
+    #[error("couldn't determine filemode: {0}")]
+    Mode(u32),
+    #[error(transparent)]
+    Atom(#[from] AtomError),
+    #[error(transparent)]
+    Doc(#[from] DocError),
+    #[error(transparent)]
+    SemverParse(#[from] semver::Error),
+    #[error(transparent)]
+    Prefix(#[from] StripPrefixError),
+    #[error("Directory depth exceeds maximum of {MAX_DEPTH}")]
+    RecursionLimit,
+    #[error("Invalid filename")]
+    InvalidFile,
+}
+
+impl<'a> RemoteAtomCache for &'a Repository {
+    type Atom = Commit<'a>;
+    type Error = Error;
+    type RemoteHandle = (Root, Remote<'a>);
+    type Transport = Box<dyn Transport + Send>;
+
+    fn ensure_remote(
+        &self,
+        url: &gix::Url,
+        transport: &mut Self::Transport,
+    ) -> Result<Self::RemoteHandle, Self::Error> {
+        use base58::ToBase58;
+
+        let query = format!("{}:{}", super::V1_ROOT, super::V1_ROOT);
+        let root = url
+            .get_ref(query.as_str(), Some(transport))
+            .map_err(Box::new)?;
+        let id = super::to_id(root);
+        let gix::ObjectId::Sha1(oid) = id;
+        let name: String = oid.to_base58();
+        let root = Root(id);
+
+        let remote = self
+            .find_remote(bstr::BString::from(name.to_owned()).as_bstr())
+            .unwrap_or(
+                self.find_remote(url.to_bstring().as_bstr())
+                    .unwrap_or(self.remote_at(url.to_owned())?),
+            );
+
+        Ok((root, remote))
+    }
+
+    fn resolve_atom_to_cache(
+        &self,
+        remote: &mut Self::RemoteHandle,
+        label: &Label,
+        version: &Version,
+        transport: &mut Self::Transport,
+    ) -> Result<Self::Atom, Self::Error> {
+        let (root, remote) = remote;
+        let id = AtomId::from((*root, label.to_owned()));
+        let cache_ref = format!("refs/{}/{}", id.compute_hash(), version);
+        let query = format!(
+            "{}/{}/{}:{}",
+            crate::ATOM_REFS.as_str(),
+            label,
+            version,
+            cache_ref
+        );
+        let r = remote
+            .get_ref(query.as_str(), Some(transport))
+            .map_err(Box::new)?;
+        let id = super::to_id(r);
+        let commit = self
+            .find_commit(id)
+            .map_err(Box::new)
+            .map_err(super::Error::NoCommit)
+            .map_err(Box::new)?;
+        Ok(commit)
+    }
+
+    fn materialize_from_cache(
+        &self,
+        cached: Self::Atom,
+        to_dir: impl AsRef<Path>,
+    ) -> Result<tempfile::TempDir, Self::Error> {
+        use std::fs;
+
+        use gix::traverse::tree::Recorder;
+
+        let tree = cached.tree()?;
+        let mut record = Recorder::default();
+        tree.traverse().depthfirst(&mut record)?;
+        let tmp = tempfile::TempDir::with_prefix_in("atom-", to_dir)?;
+
+        for entry in record.records {
+            let full_path = tmp.as_ref().join(entry.filepath.to_string());
+            match entry.mode.kind() {
+                EntryKind::Tree => {
+                    if full_path.try_exists().is_ok_and(|p| !p) {
+                        fs::create_dir_all(full_path)?;
+                    }
+                },
+                EntryKind::Blob | EntryKind::BlobExecutable => {
+                    if let Some(parent) = full_path.parent()
+                        && parent.try_exists().is_ok_and(|p| !p)
+                    {
+                        fs::create_dir_all(parent)?;
+                    }
+                    let blob = self.find_object(entry.oid)?.try_into_blob()?;
+                    fs::write(&full_path, blob.detach().data)?;
+
+                    if entry.mode.is_executable() {
+                        #[cfg(unix)]
+                        {
+                            use std::os::unix::fs::PermissionsExt;
+                            let mut perms = fs::metadata(&full_path)?.permissions();
+                            perms.set_mode(0o755);
+                            fs::set_permissions(&full_path, perms)?;
+                        }
+                        // TODO: Windows?
+                    }
+                },
+                EntryKind::Link => {
+                    if let Some(parent) = full_path.parent() {
+                        fs::create_dir_all(parent)?;
+                    }
+                    let blob = self.find_object(entry.oid)?.try_into_blob()?;
+                    let target = std::str::from_utf8(&blob.data)?;
+                    #[cfg(unix)]
+                    std::os::unix::fs::symlink(target, &full_path)?;
+                },
+                EntryKind::Commit => {
+                    tracing::warn!(ignoring = %full_path.display(), "subrepos not supported in atoms")
+                },
+            }
+        }
+
+        Ok(tmp)
+    }
+
+    fn path_to_cache(&self, path: impl AsRef<Path>) -> Result<(Version, Self::Atom), Self::Error> {
+        let manifest_path = path.as_ref().join(crate::ATOM_MANIFEST_NAME.as_str());
+        if !manifest_path.try_exists().is_ok_and(|b| b) {
+            return Err(Error::NotAnAtom(manifest_path));
+        }
+
+        let atom = ValidManifest::get_atom(
+            std::fs::read(&manifest_path)?
+                .to_str()
+                .map_err(DocError::Utf8)?,
+        )?;
+
+        let root = if let Some(g) =
+            gix::discover(path.as_ref().canonicalize()?)
+                .ok()
+                .and_then(|r| {
+                    r.head_commit()
+                        .ok()
+                        .and_then(|c| c.calculate_genesis().ok())
+                }) {
+            g
+        } else {
+            NULLROOT
+        };
+
+        let (label, mut version) = atom.take();
+
+        let id = AtomId::from((root, label));
+        let entry_map = collect_entries(path.as_ref())?;
+        let tree =
+            build_tree_recursive(self, PathBuf::new().as_path(), &entry_map, path.as_ref(), 0)?;
+
+        version.pre = Prerelease::new(format!("dev.{}", tree.to_hex_with_len(10)).as_str())?;
+        version.build = BuildMetadata::EMPTY;
+
+        let obj = *git::write_atom_commit_to_repo(
+            self,
+            tree,
+            id.label(),
+            &version,
+            root.to_hex().to_string(),
+        )
+        .map_err(Box::new)?
+        .tip();
+
+        let digest = id.compute_hash();
+
+        self.reference(
+            format!("refs/{}/{}", digest, version),
+            obj,
+            gix::refs::transaction::PreviousValue::ExistingMustMatch(gix::refs::Target::Object(
+                obj,
+            )),
+            format!("atom({}): {}", digest, version),
+        )
+        .map_err(package::publish::error::git::Error::RefUpdateFailed)
+        .map_err(Box::new)?;
+
+        Ok((
+            version,
+            self.find_commit(obj)
+                .map_err(package::publish::error::git::Error::NoCommit)
+                .map_err(Box::new)?,
+        ))
+    }
+}
+
+fn get_cache() -> Result<ThreadSafeRepository, Error> {
+    let cache_dir = config::CONFIG.cache.root.join("git");
+    Ok(ThreadSafeRepository::open(&cache_dir)
+        .or_else(|_| {
+            ThreadSafeRepository::init(
+                cache_dir,
+                Kind::Bare,
+                Options {
+                    destination_must_be_empty: true,
+                    ..Default::default()
+                },
+            )
+        })
+        .map_err(Box::new)?)
+}
+
+/// Acquire a reference to the configured global cache repository
+pub fn repo() -> Result<&'static ThreadSafeRepository, Error> {
+    let mut error = None;
+    let repo = CACHE_REPO.get_or_init(|| match get_cache() {
+        Ok(repo) => Some(repo),
+        Err(e) => {
+            error = Some(e);
+            None
+        },
+    });
+    if let Some(e) = error {
+        Err(e)
+    } else if let Some(repo) = repo {
+        Ok(repo)
+    } else {
+        let cache_dir = config::CONFIG.cache.root.join("git");
+        Err(Error::Repo(cache_dir))
+    }
+}
+
+/// Structure to hold our collected entries
+#[derive(Debug)]
+pub(crate) struct FsEntry {
+    pub path: PathBuf,
+    pub is_dir: bool,
+}
+
+/// Traverse directory with ignore crate, respecting .gitignore
+pub(crate) fn collect_entries(root: &Path) -> Result<HashMap<PathBuf, Vec<FsEntry>>, Error> {
+    use ignore::Walk;
+    let mut entries_by_dir: HashMap<PathBuf, Vec<FsEntry>> = HashMap::new();
+
+    for result in Walk::new(root) {
+        let entry = result?;
+        let path = entry.path().strip_prefix(root)?.to_path_buf();
+        let parent = path.parent().unwrap_or(Path::new(".")).to_path_buf();
+
+        let fs_entry = if root.join(&path).is_dir() {
+            FsEntry { path, is_dir: true }
+        } else {
+            FsEntry {
+                path,
+                is_dir: false,
+            }
+        };
+
+        entries_by_dir.entry(parent).or_default().push(fs_entry);
+    }
+
+    Ok(entries_by_dir)
+}
+
+const MAX_DEPTH: usize = 100;
+
+pub(crate) fn build_tree_recursive(
+    repo: &Repository,
+    current_dir: &Path,
+    entries_by_dir: &HashMap<PathBuf, Vec<FsEntry>>,
+    root_path: &Path,
+    depth: usize,
+) -> Result<ObjectId, Error> {
+    use gix::objs::tree;
+    if depth > MAX_DEPTH {
+        return Err(Error::RecursionLimit);
+    }
+
+    let mut tree_entries = Vec::new();
+
+    if let Some(entries) = entries_by_dir.get(current_dir) {
+        for entry in entries {
+            let filename = entry
+                .path
+                .file_name()
+                .and_then(|n| n.to_str())
+                .ok_or(Error::InvalidFile)?;
+
+            if entry.is_dir {
+                let subtree_id =
+                    build_tree_recursive(repo, &entry.path, entries_by_dir, root_path, depth + 1)?;
+
+                tree_entries.push(tree::Entry {
+                    mode: gix::object::tree::EntryKind::Tree.into(),
+                    oid: subtree_id,
+                    filename: filename.into(),
+                });
+            } else {
+                let full_path = root_path.join(&entry.path);
+                let content = std::fs::read(&full_path)?;
+                let blob_id = repo.write_blob(&content)?;
+
+                let metadata = full_path.metadata()?;
+                let mode = metadata.mode();
+
+                tree_entries.push(tree::Entry {
+                    mode: mode.try_into().map_err(Error::Mode)?,
+                    oid: blob_id.detach(),
+                    filename: filename.into(),
+                });
+            }
+        }
+    }
+
+    tree_entries.sort_by(|a, b| a.filename.cmp(&b.filename));
+
+    let tree = gix::objs::Tree {
+        entries: tree_entries,
+    };
+    Ok(repo.write_object(&tree)?.detach())
+}
diff --git a/crates/atom/src/storage/git/test.rs b/crates/atom/src/storage/git/test.rs
index e6e5e79..34746c7 100644
--- a/crates/atom/src/storage/git/test.rs
+++ b/crates/atom/src/storage/git/test.rs
@@ -1,49 +1,12 @@
-use tempfile::TempDir;
+//! Tests for git storage operations.
 
 use super::*;
+use crate::test::harness::init_repo_and_remote;
 
 //================================================================================================
-// Functions
+// Tests
 //================================================================================================
 
-pub(crate) fn init_repo_and_remote() -> Result<(TempDir, TempDir), anyhow::Error> {
-    use gix::actor::SignatureRef;
-    use gix::config::{File, Source};
-    let sig = SignatureRef::default();
-    let repo_dir = tempfile::tempdir()?;
-    let remote_dir = tempfile::tempdir()?;
-    let repo = gix::init(repo_dir.as_ref())?;
-    let remote = gix::init_bare(remote_dir.as_ref())?;
-    let no_parents: Vec<gix::ObjectId> = vec![];
-    let init = remote.commit_as(
-        sig,
-        sig,
-        "HEAD",
-        "init",
-        repo.empty_tree().id(),
-        no_parents.clone(),
-    )?;
-    remote.commit_as(
-        sig,
-        sig,
-        "HEAD",
-        "2nd",
-        repo.empty_tree().id(),
-        vec![init.detach()],
-    )?;
-
-    let config_file = repo.git_dir().join("config");
-    let mut config = File::from_path_no_includes(config_file.clone(), Source::Local)?;
-    let mut repo_remote =
-        repo.remote_at(format!("file://{}", remote.git_dir().display()).as_str())?;
-    repo_remote.save_as_to("origin", &mut config)?;
-    config.set_raw_value(&"user.email", "eka")?;
-    config.set_raw_value(&"user.name", "eka")?;
-    let mut file = std::fs::File::create(config_file)?;
-    config.write_to(&mut file)?;
-    Ok((repo_dir, remote_dir))
-}
-
 #[test]
 fn init_repo() -> Result<(), anyhow::Error> {
     let (dir, _remote) = init_repo_and_remote()?;
diff --git a/crates/atom/src/test/harness.rs b/crates/atom/src/test/harness.rs
new file mode 100644
index 0000000..226bd77
--- /dev/null
+++ b/crates/atom/src/test/harness.rs
@@ -0,0 +1,257 @@
+//! # Test Harness
+//!
+//! Shared utilities for creating mock atoms and repositories in tests.
+//!
+//! ## Overview
+//!
+//! This module provides the infrastructure needed to test atom operations:
+//! - `init_repo_and_remote()` - Creates temporary git repos with proper config
+//! - `MockAtom` trait - Creates mock atoms with manifests and dependencies
+//!
+//! ## Usage
+//!
+//! ```ignore
+//! use atom::test::harness::{init_repo_and_remote, MockAtom};
+//!
+//! let (repo_dir, remote_dir) = init_repo_and_remote()?;
+//! let repo = ThreadSafeRepository::open(repo_dir.as_ref())?;
+//! let (path, oid) = repo.mock("my-atom", "1.0.0").await?;
+//! ```
+
+use std::path::PathBuf;
+use std::str::FromStr;
+
+use anyhow::Context;
+use gix::{ObjectId, ThreadSafeRepository};
+use semver::Version;
+use tempfile::TempDir;
+
+use crate::EkalaManager;
+
+//================================================================================================
+// Functions
+//================================================================================================
+
+/// Creates a pair of temporary git repositories: a local repo and a bare remote.
+///
+/// The repos are configured with:
+/// - A remote named "origin" pointing to the bare remote
+/// - User email/name for commits
+/// - Initial commits in the remote
+/// - Local repo fetches from remote so they share history (same genesis)
+///
+/// Returns `(local_repo_dir, remote_dir)` - both are `TempDir` that clean up on drop.
+pub fn init_repo_and_remote() -> Result<(TempDir, TempDir), anyhow::Error> {
+    use gix::actor::SignatureRef;
+    use gix::config::{File, Source};
+
+    let sig = SignatureRef::default();
+    let repo_dir = tempfile::tempdir()?;
+    let remote_dir = tempfile::tempdir()?;
+    let repo = gix::init(repo_dir.as_ref())?;
+    let remote = gix::init_bare(remote_dir.as_ref())?;
+
+    // Create initial commits in the remote
+    let no_parents: Vec<gix::ObjectId> = vec![];
+    let init = remote.commit_as(
+        sig,
+        sig,
+        "HEAD",
+        "init",
+        remote.empty_tree().id(),
+        no_parents.clone(),
+    )?;
+    remote.commit_as(
+        sig,
+        sig,
+        "HEAD",
+        "2nd",
+        remote.empty_tree().id(),
+        vec![init.detach()],
+    )?;
+
+    // Configure local repo with remote
+    let config_file = repo.git_dir().join("config");
+    let mut config = File::from_path_no_includes(config_file.clone(), Source::Local)?;
+    let mut repo_remote =
+        repo.remote_at(format!("file://{}", remote.git_dir().display()).as_str())?;
+    repo_remote.save_as_to("origin", &mut config)?;
+    config.set_raw_value(&"user.email", "eka")?;
+    config.set_raw_value(&"user.name", "eka")?;
+    let mut file = std::fs::File::create(config_file)?;
+    config.write_to(&mut file)?;
+
+    // Fetch from remote so local shares history (uses existing storage API)
+    use crate::storage::QueryStore;
+    let repo = gix::ThreadSafeRepository::open(repo_dir.as_ref())?.to_thread_local();
+    let origin = repo.find_remote("origin")?;
+    origin.get_refs(Some("refs/heads/*:refs/heads/*"), None)?;
+
+    // Set local HEAD to point to master branch (symbolic ref, not detached)
+    if let Ok(head_ref) = repo.find_reference("refs/heads/master") {
+        // Create/update refs/heads/master with the fetched commit
+        repo.reference(
+            "refs/heads/master",
+            head_ref.id().detach(),
+            gix::refs::transaction::PreviousValue::Any,
+            "sync from remote",
+        )?;
+        // Make HEAD a symbolic reference to master (not detached)
+        std::fs::write(repo.git_dir().join("HEAD"), "ref: refs/heads/master\n")?;
+    }
+
+    Ok((repo_dir, remote_dir))
+}
+
+//================================================================================================
+// Traits
+//================================================================================================
+
+/// Trait for creating mock atoms in a repository.
+///
+/// This trait is implemented on `ThreadSafeRepository` to enable creating
+/// atoms with manifests for testing purposes.
+pub trait MockAtom {
+    /// Creates a mock atom with the given label and version.
+    ///
+    /// Returns `(manifest_path, commit_oid)`.
+    fn mock(
+        &self,
+        label: &str,
+        version: &str,
+    ) -> impl std::future::Future<Output = Result<(PathBuf, ObjectId), anyhow::Error>>;
+
+    /// Creates a mock atom with dependencies.
+    ///
+    /// Dependencies are specified as `(set_tag, label, version_req)` tuples.
+    /// The set_tag should match a set defined in the ekala.toml.
+    ///
+    /// Returns `(manifest_path, commit_oid)`.
+    ///
+    /// `remote_url` is the URL to the remote where dependencies are published.
+    fn mock_with_deps(
+        &self,
+        label: &str,
+        version: &str,
+        deps: &[(&str, &str, &str)], // (set_tag, dep_label, version_req)
+        remote_url: Option<&str>,    // Optional remote URL for the set mirror
+    ) -> impl std::future::Future<Output = Result<(PathBuf, ObjectId), anyhow::Error>>;
+}
+
+//================================================================================================
+// Impls
+//================================================================================================
+
+impl MockAtom for ThreadSafeRepository {
+    async fn mock(&self, label: &str, version: &str) -> Result<(PathBuf, ObjectId), anyhow::Error> {
+        let repo = self.to_thread_local();
+        let work_dir = repo.workdir().context("No workdir")?;
+        let atom_dir = work_dir.join(label);
+        let atom_file = atom_dir.join(crate::ATOM_MANIFEST_NAME.as_str());
+
+        let mut ekala = EkalaManager::open(self)?;
+        ekala
+            .new_atom_at_path(label.try_into()?, &atom_dir, Version::from_str(version)?)
+            .await?;
+
+        // Commit the entire workdir state using build_tree_recursive
+        let atom_oid = commit_workdir(&repo, &format!("init: {}", label))?;
+
+        Ok((atom_file, atom_oid))
+    }
+
+    /// Creates an atom with dependencies.
+    ///
+    /// `deps` is a slice of (set_tag, dep_label, version_req) tuples.
+    /// `remote_url` is the URL to the remote where dependencies are published.
+    async fn mock_with_deps(
+        &self,
+        label: &str,
+        version: &str,
+        deps: &[(&str, &str, &str)], // (set_tag, dep_label, version_req)
+        remote_url: Option<&str>,    // Optional remote URL for the set mirror
+    ) -> Result<(PathBuf, ObjectId), anyhow::Error> {
+        let repo = self.to_thread_local();
+        let work_dir = repo.workdir().context("No workdir")?;
+        let atom_dir = work_dir.join(label);
+        let atom_file = atom_dir.join(crate::ATOM_MANIFEST_NAME.as_str());
+
+        // Create base atom
+        let mut ekala = EkalaManager::open(self)?;
+        ekala
+            .new_atom_at_path(label.try_into()?, &atom_dir, Version::from_str(version)?)
+            .await?;
+
+        // Add dependencies using add_uri - the high-level API that simulates `eka add`
+        if !deps.is_empty() {
+            use crate::id::Tag;
+            use crate::package::metadata::manifest::ManifestWriter;
+            use crate::uri::Uri;
+
+            // Open the atom with ManifestWriter
+            let mut writer = ManifestWriter::open_and_resolve(self, &atom_dir, true).await?;
+
+            for (set_tag, dep_label, version_req) in deps {
+                // Construct URI with remote URL: "url::dep-label@^version" or just
+                // "dep-label@version"
+                let uri_str = if let Some(url) = remote_url {
+                    format!("{}::{}@{}", url, dep_label, version_req)
+                } else {
+                    format!("{}@{}", dep_label, version_req)
+                };
+                let uri: Uri = uri_str.parse()?;
+                let tag = Some(Tag::try_from(*set_tag)?);
+
+                // Use add_uri with additional mirrors
+                writer.add_uri(uri, tag, vec![])?;
+            }
+
+            // Write the changes
+            writer.write_atomic()?;
+        }
+
+        // Commit the entire workdir state using build_tree_recursive
+        let atom_oid = commit_workdir(&repo, &format!("init with deps: {}", label))?;
+
+        Ok((atom_file, atom_oid))
+    }
+}
+
+/// Helper to commit the entire working directory state.
+pub fn commit_workdir(repo: &gix::Repository, message: &str) -> Result<ObjectId, anyhow::Error> {
+    use std::path::PathBuf;
+
+    use crate::storage::git::cache::{build_tree_recursive, collect_entries};
+
+    let work_dir = repo.workdir().context("No workdir")?;
+
+    // Build tree from entire workdir using proper recursive function
+    let entries = collect_entries(work_dir)?;
+    let tree_oid = build_tree_recursive(repo, PathBuf::new().as_path(), &entries, work_dir, 0)?;
+
+    let head = repo.head_id()?;
+    let head_ref = repo.head_ref()?.context("detached HEAD")?;
+
+    let commit_oid = repo
+        .commit(head_ref.name().as_bstr(), message, tree_oid, vec![head])?
+        .detach();
+
+    Ok(commit_oid)
+}
+
+//================================================================================================
+// Test Helpers
+//================================================================================================
+
+/// Initializes tracing for tests (respects RUST_LOG env var).
+pub fn init_tracing() {
+    use tracing_subscriber::filter::EnvFilter;
+    use tracing_subscriber::fmt;
+    use tracing_subscriber::layer::SubscriberExt;
+    use tracing_subscriber::util::SubscriberInitExt;
+
+    let _ = tracing_subscriber::registry()
+        .with(fmt::layer().compact())
+        .with(EnvFilter::from_default_env())
+        .try_init();
+}
diff --git a/crates/atom/src/test/mod.rs b/crates/atom/src/test/mod.rs
new file mode 100644
index 0000000..5ed4344
--- /dev/null
+++ b/crates/atom/src/test/mod.rs
@@ -0,0 +1,5 @@
+//! # Test Utilities
+//!
+//! Shared test infrastructure for the atom crate.
+
+pub mod harness;
diff --git a/crates/atom/src/uri/mod.rs b/crates/atom/src/uri/mod.rs
index ae91aee..85ea23b 100644
--- a/crates/atom/src/uri/mod.rs
+++ b/crates/atom/src/uri/mod.rs
@@ -760,29 +760,4 @@ pub(crate) mod serde_gix_url {
         let str = url.to_string();
         serializer.serialize_str(&str)
     }
-
-    pub(crate) mod maybe {
-        use serde::{Deserializer, Serializer};
-        pub(crate) fn serialize<S>(
-            url: &Option<gix::url::Url>,
-            serializer: S,
-        ) -> Result<S::Ok, S::Error>
-        where
-            S: Serializer,
-        {
-            if let Some(url) = url {
-                super::serialize(url, serializer)
-            } else {
-                Err(serde::ser::Error::custom("no url to serialize"))
-            }
-        }
-        pub(crate) fn deserialize<'de, D>(
-            deserializer: D,
-        ) -> Result<Option<gix::url::Url>, D::Error>
-        where
-            D: Deserializer<'de>,
-        {
-            super::deserialize(deserializer).map(Some)
-        }
-    }
 }
diff --git a/crates/config/src/lib.rs b/crates/config/src/lib.rs
index 4f19857..2c17fe0 100644
--- a/crates/config/src/lib.rs
+++ b/crates/config/src/lib.rs
@@ -29,6 +29,12 @@ const DEFAULT_TOML_CONFIG: &str = include_str!("./eka.default.toml");
 /// application's lifecycle.
 pub static CONFIG: LazyLock<Config> = LazyLock::new(load_config);
 
+static DEFAULT_PLATFORM: LazyLock<String> =
+    LazyLock::new(|| match (std::env::consts::ARCH, std::env::consts::OS) {
+        (arch, "macos") => format!("{}-darwin", arch),
+        (arch, os) => format!("{}-{}", arch, os),
+    });
+
 //================================================================================================
 // Types
 //================================================================================================
@@ -73,6 +79,30 @@ pub struct Config {
     pub cache: CacheConfig,
     #[serde(borrow)]
     pub manifest: AtomConfig<'static>,
+    /// settings affecting the `plan` subcommand
+    pub plan: Plan,
+    /// The default platforms to consinder when not passed by the user
+    #[serde(borrow)]
+    pub platforms: Platforms<'static>,
+}
+
+#[derive(Deserialize, Serialize)]
+pub struct Platforms<'a> {
+    /// The default build platform to use when unset
+    #[serde(borrow)]
+    pub build: Cow<'a, str>,
+    /// The default runtime platform to use when unset
+    #[serde(borrow)]
+    pub target: Cow<'a, str>,
+    /// The default legacy "configuration target" used in special cases by legacy tools such as
+    /// GNU autoconf
+    #[serde(borrow)]
+    pub legacy_target: Cow<'a, str>,
+}
+
+#[derive(Deserialize, Serialize, Default)]
+pub struct Plan {
+    pub sharectx: bool,
 }
 
 #[derive(Deserialize, Serialize, Default, Clone)]
@@ -113,6 +143,16 @@ impl Default for CacheConfig {
     }
 }
 
+impl<'a> Default for Platforms<'a> {
+    fn default() -> Self {
+        Self {
+            build: DEFAULT_PLATFORM.as_str().into(),
+            target: DEFAULT_PLATFORM.as_str().into(),
+            legacy_target: DEFAULT_PLATFORM.as_str().into(),
+        }
+    }
+}
+
 impl Config {
     /// Returns a reference to the configured uri aliases.
     pub fn uri_aliases(&self) -> &Aliases<'static> {
@@ -141,7 +181,7 @@ impl Config {
             fig = fig.admerge(Toml::file(repo_config));
         };
 
-        fig.admerge(Env::prefixed("EKA_"))
+        fig.admerge(Env::prefixed("EKA_").split("_"))
     }
 
     /// Creates a `Config` instance from a given provider.
diff --git a/crates/eka-root-macro/src/lib.rs b/crates/eka-root-macro/src/lib.rs
index e81f667..a7ad08c 100644
--- a/crates/eka-root-macro/src/lib.rs
+++ b/crates/eka-root-macro/src/lib.rs
@@ -1,15 +1,9 @@
-use std::sync::atomic::AtomicBool;
-
-use gix::progress::Discard;
 use gix::revision::walk::Info;
 use gix::{ObjectId, ThreadSafeRepository};
 use proc_macro::TokenStream;
 use quote::quote;
 
 const LOCK_LABEL: &str = "nix-lock";
-const LOCK_MAJOR: u64 = 0;
-const LOCK_MINOR: u64 = 1;
-const LOCK_PATCH: u64 = 6;
 
 /// Computes Eka's repository root commit hash at compile time
 #[proc_macro]
@@ -26,31 +20,17 @@ pub fn eka_origin_info(_input: TokenStream) -> TokenStream {
         }
     };
 
+    let root_tokens = root_hash.iter().map(|&byte| quote! { #byte });
     let origin_url = if let Ok(var) = std::env::var("EKA_ORIGIN_URL") {
+        gix::url::parse(var.as_bytes().into()).expect("EKA_ORIGIN_URL is not a valid url");
         var
     } else {
         eka_origin().to_string()
     };
     let url = origin_url.as_str();
 
-    // Convert [u8; 20] to token streams for each byte
-    let root_tokens = root_hash.iter().map(|&byte| quote! { #byte });
-    let rev = if let Ok(var) = std::env::var("EKA_LOCK_REV") {
-        hex::decode(var)
-            .ok()
-            .and_then(|v| v.try_into().ok())
-            .expect("set `EKA_LOCK_REV` is not a valid sha")
-    } else {
-        lock_rev()
-    };
-    let rev_tokens = rev.iter().map(|&byte| quote! { #byte });
-
     quote! {
-        const LOCK_MAJOR: u64 = #LOCK_MAJOR;
-        const LOCK_MINOR: u64 = #LOCK_MINOR;
-        const LOCK_PATCH: u64 = #LOCK_PATCH;
         pub(crate) const LOCK_LABEL: &str = #LOCK_LABEL;
-        pub(crate) const LOCK_REV: [u8; 20] = [#(#rev_tokens),*];
         pub(crate) const EKA_ORIGIN_URL: &str = #url;
         pub(crate) const EKA_ROOT_COMMIT_HASH: [u8; 20] = [#(#root_tokens),*];
     }
@@ -65,47 +45,6 @@ fn compute_eka_root_hash() -> Result<[u8; 20], Box<dyn std::error::Error>> {
     Ok(root)
 }
 
-fn lock_rev() -> [u8; 20] {
-    let version = format!("{}.{}.{}", LOCK_MAJOR, LOCK_MINOR, LOCK_PATCH);
-    let revspec = format!("refs/eka/atoms/{}/{}", LOCK_LABEL, &version);
-
-    let repo = get_repo().to_thread_local();
-    let remote = default_remote();
-    let mut remote = repo
-        .try_find_remote_without_url_rewrite(remote.as_str())
-        .and_then(|x| x.ok())
-        .unwrap_or_else(|| panic!("couldn't open default remote: {}", remote));
-    remote
-        .replace_refspecs([revspec.as_str()], gix::remote::Direction::Fetch)
-        .ok();
-
-    if let Some(ObjectId::Sha1(bytes)) = remote
-        .connect(gix::remote::Direction::Fetch)
-        .ok()
-        .and_then(|c| c.prepare_fetch(Discard, Default::default()).ok())
-        .and_then(|q| {
-            q.with_write_packed_refs_only(true)
-                .receive(Discard, &AtomicBool::new(false))
-                .ok()
-        })
-        .and_then(|o| {
-            o.ref_map.remote_refs.iter().find_map(|r| {
-                let (n, p, _) = r.unpack();
-
-                p.and_then(|t| if n == revspec { Some(t.into()) } else { None })
-            })
-        })
-    {
-        bytes
-    } else {
-        panic!(
-            "aborting compilation. eka lock rev could not be calculated, make sure you have \
-             published first: ::{}@{}",
-            LOCK_LABEL, &version
-        )
-    }
-}
-
 fn eka_origin() -> gix::Url {
     let remote = default_remote();
     get_repo()
diff --git a/crates/nixec/Cargo.toml b/crates/nixec/Cargo.toml
index c480e58..cc8ce44 100644
--- a/crates/nixec/Cargo.toml
+++ b/crates/nixec/Cargo.toml
@@ -6,4 +6,5 @@ version = "0.1.0"
 [dependencies]
 birdcage = "^0.8"
 
+anyhow.workspace    = true
 thiserror.workspace = true
diff --git a/crates/nixec/src/lib.rs b/crates/nixec/src/lib.rs
new file mode 100644
index 0000000..d31ae39
--- /dev/null
+++ b/crates/nixec/src/lib.rs
@@ -0,0 +1,211 @@
+//! `nixec` is a sandboxed version of `nix-instantiate`.
+//!
+//! This utility wraps `nix-instantiate` in a `birdcage` sandbox to restrict its
+//! access to the file system and environment variables, enhancing security during
+//! Nix expression evaluation.
+
+use std::path::{Path, PathBuf};
+use std::process::{Command as UnsafeCommand, ExitCode};
+use std::{env, fs};
+
+use birdcage::process::Command;
+use birdcage::{Birdcage, Exception, Sandbox};
+use thiserror::Error;
+
+//================================================================================================
+// Constants
+//================================================================================================
+
+pub const WORKDIR: &str = "/work";
+const SSL_CERT_PATH: &str = "/nix/var/nix/profiles/default/etc/ssl/certs/ca-bundle.crt";
+const RESOLV_CONF_PATH: &str = "/etc/resolv.conf";
+const DEV_NULL_PATH: &str = "/dev/null";
+
+//================================================================================================
+// Types
+//================================================================================================
+
+/// Configuration for nixec execution.
+#[derive(Debug)]
+struct NixecConfig {
+    nix_dir: PathBuf,
+    git_dir: PathBuf,
+    utils_dir: PathBuf,
+    nix_store: PathBuf,
+    nix_config: String,
+}
+
+/// Represents the possible errors that can occur during `nixec` execution.
+#[derive(Error, Debug)]
+pub enum NixecError {
+    /// Error indicating that the `nix` executable could not be found in the system's PATH.
+    #[error("No `{0}` executable in PATH")]
+    NoBin(String),
+    /// Error originating from the `birdcage` sandboxing library.
+    #[error(transparent)]
+    ExceptionFailed(#[from] birdcage::error::Error),
+    /// Error from I/O operations, typically when executing a command.
+    #[error(transparent)]
+    CommandFailed(#[from] std::io::Error),
+    /// Error for UTF-8 conversion failures.
+    #[error(transparent)]
+    Utf8Error(#[from] std::string::FromUtf8Error),
+    /// Error for when the Nix store path could not be determined.
+    #[error("Failed to determine nix store path")]
+    StorePath,
+}
+
+//================================================================================================
+// Functions
+//================================================================================================
+
+/// Sets up the necessary paths and configuration for nixec.
+fn setup_paths() -> Result<NixecConfig, NixecError> {
+    let nix_dir = bin_dir("nix")?;
+    let git_dir = bin_dir("git")?;
+    let utils_dir = bin_dir("coreutils")?;
+    let nix_instantiate = nix_dir.join("nix-instantiate");
+    let nix = nix_dir.join("nix");
+
+    let nix_store: PathBuf = String::from_utf8(
+        UnsafeCommand::new(&nix_instantiate)
+            .args(["--eval", "--raw", "--expr", "builtins.storeDir"])
+            .output()?
+            .stdout,
+    )
+    .map_err(|_| NixecError::StorePath)?
+    .trim()
+    .into();
+
+    let nix_config: String = String::from_utf8(
+        UnsafeCommand::new(&nix)
+            .args(["config", "show"])
+            .output()?
+            .stdout,
+    )?
+    .trim()
+    .lines()
+    .chain([
+        format!("ssl-cert-file = {}", SSL_CERT_PATH).as_str(),
+        "pure-eval = false",
+        "restrict-eval = true",
+        // FIXME: hardcoded for now, should allow setting externally
+        "allowed-uris = git+https: https: ssh: git+ssh:",
+    ])
+    .collect::<Vec<&str>>()
+    .join("\n");
+
+    Ok(NixecConfig {
+        nix_dir,
+        git_dir,
+        utils_dir,
+        nix_store,
+        nix_config,
+    })
+}
+
+/// Configures the sandbox with necessary exceptions and environment variables.
+fn configure_sandbox(config: &NixecConfig) -> Result<Birdcage, NixecError> {
+    let cwd = env::current_dir()?;
+    let mut sandbox = Birdcage::new();
+
+    if let Ok(home) = std::env::var("HOME") {
+        let cache = std::env::var("XDG_CACHE_HOME")
+            .map(PathBuf::from)
+            .unwrap_or(PathBuf::from(home).join(".cache"));
+        unsafe { env::set_var("XDG_CACHE_HOME", &cache) };
+        sandbox
+            .add_exception(Exception::Environment("XDG_CACHE_HOME".into()))?
+            .add_exception(Exception::WriteAndRead(cache.join("nix")))?;
+    };
+
+    let nix_root = config
+        .nix_store
+        .parent()
+        .map(Path::to_path_buf)
+        .ok_or(NixecError::StorePath)?;
+
+    unsafe { env::set_var("NIX_CONFIG", &config.nix_config) };
+    unsafe {
+        env::set_var(
+            "PATH",
+            format!(
+                "{}:{}:{}",
+                config.nix_dir.display(),
+                config.git_dir.display(),
+                config.utils_dir.display()
+            ),
+        )
+    };
+    unsafe { env::set_var("GIT_SSL_CAINFO", SSL_CERT_PATH) };
+    unsafe { env::set_var("NIX_PATH", WORKDIR) };
+    unsafe { env::set_var("HOME", "/homeless-shelter") };
+    sandbox
+        .add_exception(Exception::Environment("HOME".into()))?
+        .add_exception(Exception::Environment("NIX_CONFIG".into()))?
+        .add_exception(Exception::Environment("NIX_PATH".into()))?
+        .add_exception(Exception::Environment("PATH".into()))?
+        .add_exception(Exception::Environment("GIT_SSL_CAINFO".into()))?
+        .add_exception(Exception::Read(cwd))?
+        .add_exception(Exception::Read(RESOLV_CONF_PATH.into()))?
+        .add_exception(Exception::ExecuteAndRead(nix_root))?
+        .add_exception(Exception::ExecuteAndRead(config.nix_dir.clone()))?
+        .add_exception(Exception::ExecuteAndRead(config.git_dir.clone()))?
+        .add_exception(Exception::ExecuteAndRead(config.utils_dir.clone()))?
+        .add_exception(Exception::WriteAndRead(DEV_NULL_PATH.into()))?
+        .add_exception(Exception::Networking)?;
+
+    Ok(sandbox)
+}
+
+/// Runs the nix-instantiate command within the configured sandbox.
+fn run_command_in_sandbox(
+    config: &NixecConfig,
+    sandbox: Birdcage,
+    args: &[String],
+) -> Result<ExitCode, NixecError> {
+    let nix_instantiate = config.nix_dir.join("nix-instantiate");
+    let mut command = Command::new(nix_instantiate);
+    command.args(args);
+
+    let output = sandbox.spawn(command)?.wait_with_output()?;
+
+    Ok(ExitCode::from(output.status.code().unwrap_or(1) as u8))
+}
+
+/// Runs nixec with the given arguments. This is the main logic that can be called for testing.
+pub fn run_nixec(args: Vec<String>) -> Result<ExitCode, NixecError> {
+    let config = setup_paths()?;
+    let sandbox = configure_sandbox(&config)?;
+    let sandbox_args = &args[1..]; // Assuming args[0] is program name
+    run_command_in_sandbox(&config, sandbox, sandbox_args)
+}
+
+/// The main entry point for the `nixec` executable.
+pub fn main() -> anyhow::Result<ExitCode> {
+    let args: Vec<String> = env::args().collect();
+    run_nixec(args).map_err(Into::into)
+}
+
+/// Locates the directory containing a given executable.
+///
+/// This function searches the directories listed in the `PATH` environment variable
+/// to find the specified executable and returns its parent directory.
+fn bin_dir(exec_name: &str) -> Result<PathBuf, NixecError> {
+    env::var_os("PATH")
+        .and_then(|paths| {
+            env::split_paths(&paths)
+                .filter_map(|dir| {
+                    let full_path = dir.join(exec_name);
+                    if full_path.is_file() {
+                        fs::canonicalize(full_path)
+                            .ok()
+                            .and_then(|p| p.parent().map(Path::to_path_buf))
+                    } else {
+                        None
+                    }
+                })
+                .next()
+        })
+        .ok_or(NixecError::NoBin(exec_name.into()))
+}
diff --git a/crates/nixec/src/main.rs b/crates/nixec/src/main.rs
index 9974924..1c88c44 100644
--- a/crates/nixec/src/main.rs
+++ b/crates/nixec/src/main.rs
@@ -1,109 +1 @@
-//! `nixec` is a sandboxed version of `nix-instantiate`.
-//!
-//! This utility wraps `nix-instantiate` in a `birdcage` sandbox to restrict its
-//! access to the file system and environment variables, enhancing security during
-//! Nix expression evaluation.
-
-use std::path::{Path, PathBuf};
-use std::process::{Command as UnsafeCommand, ExitCode};
-use std::{env, fs};
-
-use birdcage::process::Command;
-use birdcage::{Birdcage, Exception, Sandbox};
-use thiserror::Error;
-
-//================================================================================================
-// Types
-//================================================================================================
-
-/// Represents the possible errors that can occur during `nixec` execution.
-#[derive(Error, Debug)]
-enum NixecError {
-    /// Error indicating that the `nix` executable could not be found in the system's PATH.
-    #[error("No `nix` executable in PATH")]
-    NoNix,
-    /// Error originating from the `birdcage` sandboxing library.
-    #[error(transparent)]
-    ExceptionFailed(#[from] birdcage::error::Error),
-    /// Error from I/O operations, typically when executing a command.
-    #[error(transparent)]
-    CommandFailed(#[from] std::io::Error),
-    /// Error for when the Nix store path could not be determined.
-    #[error("Failed to determine nix store path")]
-    StorePath,
-}
-
-/// A specialized `Result` type for `nixec` operations.
-type Result<T> = std::result::Result<T, NixecError>;
-
-//================================================================================================
-// Functions
-//================================================================================================
-
-/// Locates the directory containing a given executable.
-///
-/// This function searches the directories listed in the `PATH` environment variable
-/// to find the specified executable and returns its parent directory.
-fn bin_dir(exec_name: &str) -> Result<PathBuf> {
-    env::var_os("PATH")
-        .and_then(|paths| {
-            env::split_paths(&paths)
-                .filter_map(|dir| {
-                    let full_path = dir.join(exec_name);
-                    if full_path.is_file() {
-                        fs::canonicalize(full_path)
-                            .ok()
-                            .and_then(|p| p.parent().map(Path::to_path_buf))
-                    } else {
-                        None
-                    }
-                })
-                .next()
-        })
-        .ok_or(NixecError::NoNix)
-}
-
-/// The main entry point for the `nixec` executable.
-///
-/// This function sets up the sandbox, determines the Nix store path, and executes
-/// `nix-instantiate` with the provided arguments within the sandbox.
-fn main() -> Result<ExitCode> {
-    let nix_dir = bin_dir("nix")?;
-    let nix_instantiate = nix_dir.join("nix-instantiate");
-    let cwd = env::current_dir()?;
-
-    let args: Vec<String> = env::args().collect();
-    let sandbox_args = &args[1..];
-
-    let mut sandbox = Birdcage::new();
-
-    sandbox.add_exception(Exception::Read(cwd))?;
-
-    let nix_store: PathBuf = String::from_utf8(
-        UnsafeCommand::new(nix_instantiate.clone())
-            .args(["--eval", "--expr", "builtins.storeDir"])
-            .output()?
-            .stdout,
-    )
-    .map_err(|_| NixecError::StorePath)?
-    .trim()
-    .trim_matches('"')
-    .into();
-
-    sandbox.add_exception(Exception::ExecuteAndRead(
-        nix_store
-            .parent()
-            .map(Path::to_path_buf)
-            .ok_or(NixecError::StorePath)?,
-    ))?;
-    unsafe { env::set_var("HOME", "/homeless-shelter") };
-    sandbox.add_exception(Exception::Environment("HOME".into()))?;
-
-    sandbox.add_exception(Exception::ExecuteAndRead(nix_dir))?;
-    let mut command = Command::new(nix_instantiate);
-    command.args(sandbox_args);
-
-    let output = sandbox.spawn(command)?.wait_with_output()?;
-
-    Ok(ExitCode::from(output.status.code().unwrap_or(1) as u8))
-}
+pub use nixec::main;
diff --git a/dev/atom.lock b/dev/atom.lock
index 0ff1088..8e52edf 100644
--- a/dev/atom.lock
+++ b/dev/atom.lock
@@ -2,11 +2,15 @@
 # It is not intended for manual editing.
 version = 1
 
+[sets.68b63bd131acd23bdfd57983fe85ba7c092ce02f]
+tag = "atom"
+mirrors = ["https://github.com/ekala-project/atom"]
+
 [locker]
 label = "nix-lock"
-version = "0.1.0"
+version = "0.3.1"
 set = "4abbd2644bc3585e9be95deb277ccf48f6ed26ac"
-rev = "d4f261e4f8dd43e2285a85b2bef03c0add219657"
+rev = "dc7891b2a0b456d673d522dcc539ce6608713c6a"
 mirror = "https://github.com/ekala-project/eka"
 id = "r3rlam6bd31t9i04ggug7avs8vf8981q7a3b6gobemk1gfs50qm0"
 
@@ -20,10 +24,6 @@ mirror = "https://github.com/ekala-project/atom"
 id = "r9ilp2p4bpkup8bejuqrg042m6ohc0rtcn2fks94otlrhnquhnv0"
 entry = "env"
 
-[sets.68b63bd131acd23bdfd57983fe85ba7c092ce02f]
-tag = "atom"
-mirrors = ["https://github.com/ekala-project/atom"]
-
 [[deps]]
 type = "nix+git"
 name = "fenix"
diff --git a/dev/default.nix b/dev/default.nix
index e5f2137..546d5a1 100644
--- a/dev/default.nix
+++ b/dev/default.nix
@@ -4,15 +4,17 @@ let
   inherit (lock) locker;
   lockexpr =
     import
-    <| builtins.fetchGit {
+    <| (builtins.fetchGit {
       inherit (locker) rev;
       name = locker.label;
       url = locker.mirror;
       ref = "refs/eka/atoms/${locker.label}/${locker.version}";
-    };
+    }) + "/atom.nix";
 in
-lockexpr ./. lockstr {
-  extraConfig = {
-    platform = builtins.currentSystem or "x86_64-linux";
+lockexpr {
+  root = ./.;
+  config = {
+    platforms.build = builtins.currentSystem or "x86_64-linux";
+    platforms.target = builtins.currentSystem or "x86_64-linux";
   };
 }
diff --git a/dev/env/mod.nix b/dev/env/mod.nix
index 1d73a9e..e821546 100644
--- a/dev/env/mod.nix
+++ b/dev/env/mod.nix
@@ -1,14 +1,16 @@
 let
   inherit (deps) pins;
-  system = cfg.platform;
 in
-{
+rec {
+  Main = Shell;
   Shell = mod.shell mod.pkgs;
   Static = mod.shell mod.pkgs.pkgsStatic;
   Pkgs = mod.pkgs;
-  pkgs = pins.nixpkgs.import "" { inherit system; };
+  pkgs = pins.nixpkgs.import "" {
+    system = cfg.platforms.build;
+    crossSystem = cfg.platforms.target or cfg.platforms.build;
+  };
   fenix = pins.fenix.import "" {
-    inherit system;
     inherit (mod) pkgs;
   };
   Toolchain = mod.fenix.fromToolchainFile { file = "${mod}/rust-toolchain.toml"; };
diff --git a/dev/env/shell.nix b/dev/env/shell.nix
index 10543e4..475082b 100644
--- a/dev/env/shell.nix
+++ b/dev/env/shell.nix
@@ -19,6 +19,7 @@ pkgs.mkShell.override { stdenv = pkgs.clangStdenv; } {
       pkg-config
       nodePackages.prettier
       mod.fenix.default.rustfmt
+      crate2nix
       nil
       toolchain
       mold
diff --git a/nix-lock/atom.nix b/nix-lock/atom.nix
new file mode 100644
index 0000000..545aa1e
--- /dev/null
+++ b/nix-lock/atom.nix
@@ -0,0 +1,101 @@
+{
+  root ? ./.,
+  config ? { },
+  # FIXME: strictly for compatibility until eka has a calling interface
+  extraExtern ? { },
+}:
+let
+  inherit (import ./scope.nix config) Scoped Import;
+
+  fix =
+    f:
+    let
+      x = f x;
+    in
+    x;
+
+  locker = import ./locker.nix;
+  dep-key = import ./dep-key.nix;
+  errors = import ./errors.nix;
+  closure = import ./closure.nix root;
+
+  keys = {
+    atom = "from";
+    "nix+src" = "get";
+  };
+
+  f =
+    root': all-deps:
+    let
+      lock = (locker root').toml;
+      entrypoint = lock.compose.entry or "";
+      composer = import ./composer.nix { inherit lock errors dep-key; } Scoped all-deps;
+    in
+    if lock.version or { } == 0 || lock.static or false then
+      let
+        deps = builtins.foldl' (
+          acc: dep:
+          let
+            handled = all-deps.${dep-key dep};
+            key = keys.${dep.type} or "pins";
+            set = lock.sets."${dep.set or ""}".tag or null;
+          in
+          acc
+          // {
+            ${key} =
+              if set != null && dep ? label then
+                acc.${key} or { }
+                // {
+                  ${set} = acc.${key}.${set} or { } // {
+                    ${dep.label} = handled;
+                  };
+                }
+              else
+                acc.${key} or { } // { ${dep.name} = handled; };
+          }
+        ) { } lock.deps;
+        atom = composer (root' + "/${entrypoint}") {
+          extern = extraExtern // {
+            inherit deps;
+          };
+          config =
+            let
+              manifest_str = builtins.readFile (root' + "/atom.toml");
+              set =
+                if builtins.isAttrs config then
+                  config
+                else if builtins.isString config then
+                  let
+                    json = builtins.fromJSON config;
+                  in
+                  if builtins.isAttrs json then json else abort errors.configError
+                else
+                  abort errors.configErr;
+            in
+            set // { inherit (builtins.fromTOML manifest_str) package; };
+        };
+      in
+      atom
+    else
+      abort "unsupported format version";
+
+in
+(fix (
+  deps:
+  builtins.listToAttrs (
+    map (dep: {
+      name = dep.key;
+      value =
+        if dep.type == "atom" then
+          f dep.node.root deps
+        else if dep.type == "nix+src" then
+          { src = dep.node.root; }
+        else
+          {
+            import = path: Import (dep.node.root + "/${path}");
+            src = dep.node.root;
+          };
+
+    }) closure
+  )
+)).root
diff --git a/nix-lock/atom.toml b/nix-lock/atom.toml
index 8b01128..7476687 100644
--- a/nix-lock/atom.toml
+++ b/nix-lock/atom.toml
@@ -1,6 +1,6 @@
 [package]
 label   = "nix-lock"
-version = "0.1.6"
+version = "0.4.1"
 
 [locker.eka]
 root_hash = "4abbd2644bc3585e9be95deb277ccf48f6ed26ac"
diff --git a/nix-lock/closure.nix b/nix-lock/closure.nix
new file mode 100644
index 0000000..221780d
--- /dev/null
+++ b/nix-lock/closure.nix
@@ -0,0 +1,46 @@
+root:
+let
+  rootLock = locker root;
+
+  LocalSet = import ./locals.nix root;
+  isLocalSet = builtins.mapAttrs (_: v: builtins.elem "::" v.mirrors) rootLock.toml.sets or { };
+
+  fetchers = import ./fetch.nix { inherit LocalSet isLocalSet; };
+
+  dep-key = import ./dep-key.nix;
+  locker = import ./locker.nix;
+
+  top-level =
+    let
+      lock = rootLock.toml;
+    in
+    {
+      inherit (lock) deps;
+      node = { inherit root; };
+      key = "root";
+      type = "atom";
+    };
+
+in
+builtins.genericClosure {
+  startSet = [ top-level ];
+  operator =
+    item:
+    map (
+      dep:
+      let
+        node = fetchers.${dep.type} dep;
+      in
+      {
+        inherit node;
+        inherit (dep) type;
+        key = dep-key dep;
+      }
+      // (
+        let
+          lock = locker node.root;
+        in
+        if dep.type == "atom" && lock.toml ? deps then { inherit (lock.toml) deps; } else { }
+      )
+    ) item.deps or [ ];
+}
diff --git a/nix-lock/composer.nix b/nix-lock/composer.nix
new file mode 100644
index 0000000..ca0dc66
--- /dev/null
+++ b/nix-lock/composer.nix
@@ -0,0 +1,32 @@
+{
+  lock,
+  errors,
+  dep-key,
+}:
+Scoped: deps:
+let
+  staticComposer =
+    root: _:
+    let
+      tomlPath = root + "/atom.toml";
+    in
+    if builtins.pathExists tomlPath then builtins.fromTOML (builtins.readFile tomlPath) else { };
+  trvialComposer =
+    root: args:
+    Scoped {
+      atoms = args.extern or { };
+      cfg = args.config or { };
+    } root;
+in
+let
+  kind = lock.compose.use or (if lock.static or false then "static" else "");
+  key = builtins.hashString "sha256" (kind + lock.compose.at or "");
+in
+if kind == "nix" then
+  trvialComposer
+else if kind == "static" then
+  staticComposer
+else if kind != "" && lock.compose ? at && deps ? "${key}" then
+  deps.${key}
+else
+  abort errors.unknownErr
diff --git a/nix-lock/default.nix b/nix-lock/default.nix
deleted file mode 100644
index 4167259..0000000
--- a/nix-lock/default.nix
+++ /dev/null
@@ -1,179 +0,0 @@
-root: lockstr:
-{
-  # FIXME: strictly for compatibility until eka has a calling interface
-  extraExtern ? { },
-  extraConfig ? { },
-}:
-let
-  unknownErr = "unknown atom type encountered";
-  lock_toml = builtins.fromTOML lockstr;
-  f =
-    root: lock:
-    let
-      localSet =
-        let
-          builder =
-            path:
-            let
-              ekala = path + "/ekala.toml";
-              hasSet = builtins.readFileType path == "directory" && builtins.pathExists ekala;
-              toml = builtins.fromTOML (builtins.readFile ekala);
-              locals = builtins.listToAttrs (
-                map (
-                  rel:
-                  let
-                    toml_path = path + "/${rel}/atom.toml";
-                    atom = builtins.fromTOML (builtins.readFile toml_path);
-                  in
-                  {
-                    name = atom.package.label;
-                    value = dirOf toml_path;
-                  }
-                ) toml.set.packages
-              );
-            in
-            if path == /. || path == "/" then
-              { }
-            else if hasSet then
-              locals
-            else
-              builder (dirOf path);
-        in
-        builder root;
-      entrypoint = lock.compose.entry or "";
-      isLocalSet = builtins.mapAttrs (_: v: builtins.elem "::" v.mirrors) lock.sets;
-      composer =
-        let
-          staticComposer =
-            root: _:
-            let
-              tomlPath = root + "/atom.toml";
-            in
-            if builtins.pathExists tomlPath then builtins.fromTOML (builtins.readFile tomlPath) else { };
-          trvialComposer =
-            root: args:
-            scopedImport {
-              atoms = args.extern or { };
-              cfg = args.config or { };
-            } root;
-        in
-        let
-          composeKind = lock.compose.use or null;
-        in
-        if composeKind == "atom" then
-          handlers.atom lock.compose
-        else if composeKind == "nix" then
-          trvialComposer
-        else if composeKind == "static" then
-          staticComposer
-        else
-          abort unknownErr;
-      handlers = {
-        atom =
-          dep:
-          let
-            fetch =
-              if isLocalSet."${dep.set}" && localSet ? ${dep.label} then
-                localSet.${dep.label}
-              else
-                builtins.fetchGit {
-                  name = dep.label;
-                  inherit (dep) rev;
-                  ref = "refs/eka/atoms/${dep.label}/${dep.version}";
-                  url = dep.mirror;
-                };
-            lockPath = fetch + "/atom.lock";
-            lockstr = if builtins.pathExists lockPath then builtins.readFile lockPath else "";
-            thisLock = builtins.fromTOML lockstr;
-          in
-          f fetch thisLock;
-        "nix+git" =
-          dep:
-          let
-            fetch = builtins.fetchGit {
-              inherit (dep) rev url;
-              shallow = true;
-            };
-          in
-          {
-            import = path: import (fetch + "/${path}");
-            src = fetch;
-          };
-        "nix+tar" =
-          dep:
-          let
-            fetch = builtins.fetchTarball {
-              inherit (dep) url;
-              sha256 = dep.hash;
-            };
-          in
-          {
-            import = path: import (fetch + "/${path}");
-            src = fetch;
-          };
-        "nix" =
-          dep:
-          let
-            fetch = builtins.fetchurl {
-              inherit (dep) url;
-              sha256 = dep.hash;
-            };
-          in
-          {
-            import = path: import (fetch + "/${path}");
-            src = fetch;
-          };
-        "nix+src" =
-          dep:
-          let
-            fetch = import <nix/fetchurl.nix> {
-              inherit (dep) url hash;
-            };
-          in
-          {
-            src = fetch;
-          };
-      };
-      keys = {
-        atom = "from";
-        "nix+src" = "get";
-      };
-    in
-    if lock.version == 1 then
-      let
-        deps = builtins.foldl' (
-          acc: dep:
-          let
-            handled = handlers."${dep.type or (abort unknownErr)}" dep;
-            key = keys.${dep.type} or "pins";
-            set = lock.sets."${dep.set or "nil"}".tag or null;
-          in
-          acc
-          // {
-            ${key} =
-              if set != null && dep ? label then
-                acc.${key} or { }
-                // {
-                  ${set} = acc.${key}.${set} or { } // {
-                    ${dep.label} = handled;
-                  };
-                }
-              else
-                acc.${key} or { } // { ${dep.name} = handled; };
-          }
-        ) { } lock.deps;
-      in
-      composer (root + "/${entrypoint}") {
-        extern = extraExtern // {
-          inherit deps;
-        };
-        config =
-          let
-            manifest_str = builtins.readFile (root + "/atom.toml");
-          in
-          extraConfig // { inherit (builtins.fromTOML manifest_str) package; };
-      }
-    else
-      abort "unsupported format version";
-in
-f root lock_toml
diff --git a/nix-lock/dep-key.nix b/nix-lock/dep-key.nix
new file mode 100644
index 0000000..f965500
--- /dev/null
+++ b/nix-lock/dep-key.nix
@@ -0,0 +1,5 @@
+dep:
+if dep.type == "atom" then
+  builtins.hashString "sha256" (dep.id + dep.version)
+else
+  dep.rev or dep.hash
diff --git a/nix-lock/errors.nix b/nix-lock/errors.nix
new file mode 100644
index 0000000..8ed0a62
--- /dev/null
+++ b/nix-lock/errors.nix
@@ -0,0 +1,4 @@
+{
+  unknownErr = "unknown atom type encountered";
+  configErr = "passed configuration must be a json object";
+}
diff --git a/nix-lock/fetch.nix b/nix-lock/fetch.nix
new file mode 100644
index 0000000..cd78c0d
--- /dev/null
+++ b/nix-lock/fetch.nix
@@ -0,0 +1,63 @@
+{ LocalSet, isLocalSet }:
+{
+  atom =
+    dep:
+    let
+      root =
+        if isLocalSet."${dep.set}" or false && LocalSet ? ${dep.label} then
+          LocalSet.${dep.label}
+        else
+          builtins.fetchGit {
+            name = dep.label;
+            inherit (dep) rev;
+            ref = "refs/eka/atoms/${dep.label}/${dep.version}";
+            url = dep.mirror;
+          };
+    in
+    {
+      inherit root;
+    };
+  "nix+git" =
+    dep:
+    let
+      fetch = builtins.fetchGit {
+        inherit (dep) rev url;
+        shallow = true;
+      };
+    in
+    {
+      root = fetch;
+    };
+  "nix+tar" =
+    dep:
+    let
+      fetch = builtins.fetchTarball {
+        inherit (dep) url;
+        sha256 = dep.hash;
+      };
+    in
+    {
+      root = fetch;
+    };
+  "nix" =
+    dep:
+    let
+      fetch = builtins.fetchurl {
+        inherit (dep) url;
+        sha256 = dep.hash;
+      };
+    in
+    {
+      root = fetch;
+    };
+  "nix+src" =
+    dep:
+    let
+      fetch = import <nix/fetchurl.nix> {
+        inherit (dep) url hash;
+      };
+    in
+    {
+      root = fetch;
+    };
+}
diff --git a/nix-lock/locals.nix b/nix-lock/locals.nix
new file mode 100644
index 0000000..b874b0f
--- /dev/null
+++ b/nix-lock/locals.nix
@@ -0,0 +1,31 @@
+root:
+let
+  builder =
+    path:
+    let
+      ekala = path + "/ekala.toml";
+      hasSet =
+        builtins.readFileType path == "directory" && builtins.isPath ekala && builtins.pathExists ekala;
+      toml = builtins.fromTOML (builtins.readFile ekala);
+      locals = builtins.listToAttrs (
+        map (
+          rel:
+          let
+            toml_path = path + "/${rel}/atom.toml";
+            atom = builtins.fromTOML (builtins.readFile toml_path);
+          in
+          {
+            name = atom.package.label;
+            value = dirOf toml_path;
+          }
+        ) toml.set.packages
+      );
+    in
+    if path == /. || path == "/" then
+      { }
+    else if hasSet then
+      locals
+    else
+      builder (dirOf path);
+in
+builder root
diff --git a/nix-lock/locker.nix b/nix-lock/locker.nix
new file mode 100644
index 0000000..c409de7
--- /dev/null
+++ b/nix-lock/locker.nix
@@ -0,0 +1,9 @@
+root: rec {
+  lockstr =
+    let
+      path = root + "/atom.lock";
+    in
+    if builtins.pathExists path then builtins.readFile path else "static = true";
+
+  toml = builtins.fromTOML lockstr;
+}
diff --git a/nix-lock/scope.nix b/nix-lock/scope.nix
new file mode 100644
index 0000000..38142c5
--- /dev/null
+++ b/nix-lock/scope.nix
@@ -0,0 +1,34 @@
+{
+  platforms ? { },
+  ...
+}:
+let
+  Import = scopedImport pureScope;
+  Scoped = args: scopedImport (args // pureScope);
+  pureScope =
+    let
+      _builtins = builtins;
+    in
+    rec {
+      import = Import;
+      scopedImport = Scoped;
+      __getEnv = _: "";
+      __nixPath = [ ];
+      __currentTime = 0;
+      __currentSystem =
+        platforms.build
+          or (abort "Accessing the current system is impure. Set the platform in the config instead");
+      __storePath = abort "Making explicit dependencies on store paths is illegal.";
+      builtins = _builtins // {
+        inherit import scopedImport;
+        getEnv = __getEnv;
+        nixPath = __nixPath;
+        currentTime = __currentTime;
+        currentSystem = __currentSystem;
+        builtins = builtins;
+      };
+    };
+in
+{
+  inherit Scoped Import;
+}
diff --git a/src/cli/commands/mod.rs b/src/cli/commands/mod.rs
index cecc08d..a3a7018 100644
--- a/src/cli/commands/mod.rs
+++ b/src/cli/commands/mod.rs
@@ -4,6 +4,7 @@
 //! handling its own arguments and logic. The `run` function in this module
 //! dispatches to the appropriate subcommand based on the parsed arguments.
 
+use atom::storage::LocalStoragePath;
 use clap::Subcommand;
 
 use super::Args;
@@ -12,6 +13,7 @@ use crate::cli::store;
 mod add;
 mod init;
 mod new;
+mod plan;
 mod publish;
 mod resolve;
 
@@ -55,6 +57,12 @@ pub(super) enum Commands {
     /// specified remote for publishing atoms if not already setup.
     #[command(verbatim_doc_comment)]
     Init(init::Args),
+    /// Formulate an atom's build plan.
+    ///
+    /// This command will evaluate the expressions contained in an atom to produce a build recipe
+    /// (e.g. a nix derivation) for later execution.
+    #[command(verbatim_doc_comment)]
+    Plan(plan::Args),
 }
 
 //================================================================================================
@@ -85,6 +93,15 @@ pub async fn run(args: Args) -> anyhow::Result<()> {
         (Commands::Init(args), storage) => {
             init::run(storage, args)?;
         },
+        (Commands::Plan(args), store::Detected::Git(repo)) => {
+            plan::run(Some(repo), args).await?;
+        },
+        (Commands::Plan(args), store::Detected::FileStorage(fs)) => {
+            plan::run(Some(&fs), args).await?
+        },
+        (Commands::Plan(args), store::Detected::None) => {
+            plan::run(Option::<&LocalStoragePath>::None, args).await?
+        },
         _ => (),
     }
     Ok(())
diff --git a/src/cli/commands/plan/mod.rs b/src/cli/commands/plan/mod.rs
new file mode 100644
index 0000000..1f140bd
--- /dev/null
+++ b/src/cli/commands/plan/mod.rs
@@ -0,0 +1,285 @@
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::process::ExitStatus;
+
+use anyhow::anyhow;
+use atom::Lockfile;
+use atom::storage::git::NIX_IMPORT_FILE;
+use atom::storage::{LocalStorage, QueryStore, QueryVersion, RemoteAtomCache, git};
+use atom::uri::Uri;
+use clap::Parser;
+use config::CONFIG;
+use semver::VersionReq;
+use tempfile::TempDir;
+use tokio::task::JoinSet;
+
+#[derive(Parser, Debug)]
+#[command(next_help_heading = "Plan Options", arg_required_else_help = true)]
+#[group(id = "plan_args")]
+pub struct Args {
+    /// The atom uris to generate a plan for.
+    #[clap(required = true)]
+    uri: Vec<Uri>,
+    /// Evaluate all the atoms in a shared evaluation context. The default is derived from the
+    /// "eka.toml" via `plan.sharectx`, and is `false` if unset.
+    #[clap(
+        long,
+        short = 'c',
+        env = "EKA_PLAN_SHARECTX",
+        default_value_t = CONFIG.plan.sharectx
+    )]
+    share_context: bool,
+    /// The platform which the build will run on. The default is derived from the "eka.toml" via
+    /// `platforms.build` and falls back to the platform eka itself was compiled on if unset.
+    #[clap(long, default_value_t = CONFIG.platforms.build.to_string(), env = "EKA_PLATFORMS_BUILD")]
+    build_platform: String,
+    /// The platform the final artifact will run on. The default is derived from the "eka.toml" via
+    /// `platforms.target` and falls back to the platform eka itself was compiled on if unset.
+    #[clap(long, short, default_value_t = CONFIG.platforms.target.to_string(), env = "EKA_PLATFORMS_TARGET", name = "PLATFORM")]
+    target: String,
+    /// The platform used by legacy toolchains to specify the platform generated code will run on.
+    #[clap(long, short, default_value_t = CONFIG.platforms.legacy_target.to_string(), hide = true, env = "EKA_PLATFORMS_LEGACY_TARGET")]
+    legacy_target: String,
+}
+
+pub async fn run(storage: Option<&impl LocalStorage>, args: Args) -> anyhow::Result<()> {
+    let mut tasks = JoinSet::new();
+    let cache = git::cache_repo()?;
+    let eval_tmp = tempfile::TempDir::with_prefix(".eval-atoms-")?;
+    let mut atom_dirs: Vec<TempDir> = Vec::with_capacity(args.uri.len());
+    let mut local_atom_dirs: Vec<PathBuf> = Vec::with_capacity(args.uri.len());
+    let context = args.share_context;
+
+    let platforms = config::Platforms {
+        build: Cow::Owned(args.build_platform),
+        target: Cow::Owned(args.target),
+        legacy_target: Cow::Owned(args.legacy_target),
+    };
+
+    let local = eval_tmp.as_ref().join("local");
+    let ekala = storage.map(|s| s.ekala_manifest());
+    for uri in args.uri {
+        if let Some(url) = uri.url().map(ToOwned::to_owned) {
+            let dir = eval_tmp.as_ref().to_owned();
+            let mut transport = url.get_transport()?;
+            tasks.spawn_blocking(move || {
+                let star = VersionReq::STAR;
+                let req = uri.version().unwrap_or(&star);
+                match url.get_highest_match(uri.label(), req, Some(&mut transport)) {
+                    Some((version, _)) => {
+                        let repo = &cache.to_thread_local();
+                        match repo.cache_and_materialize_atom(
+                            &url,
+                            uri.label(),
+                            &version,
+                            &mut transport,
+                            dir,
+                        ) {
+                            Ok(dir) => Some(dir),
+                            Err(e) => {
+                                tracing::error!("{}", e);
+                                None
+                            },
+                        }
+                    },
+                    None => {
+                        tracing::warn!(
+                            label = %uri.label(),
+                            url = %url,
+                            requested = %req,
+                            "skipped: couldn't acquire requested atom uri from remote"
+                        );
+                        None
+                    },
+                }
+            });
+        } else if let Some(storage) = storage
+            && let Some(ekala) = &ekala
+        {
+            let ekala = match ekala {
+                Ok(e) => e,
+                Err(e) => return Err(anyhow!(e.to_string())),
+            };
+            let root = storage.ekala_root_dir()?;
+
+            if !local.is_symlink() {
+                #[cfg(unix)]
+                std::os::unix::fs::symlink(root, &local)?;
+            }
+
+            if let Some(path) = ekala.set().packages().as_ref().get_by_left(uri.label()) {
+                // FIXME: this entire block should probably be abstracted in library code
+                // but the current implementation does not import into the cache, which we
+                // will need to do for evaluatoin caching later.
+                let full_path = local.join(path);
+                let atom_nix = full_path.join(NIX_IMPORT_FILE);
+
+                if !atom_nix.exists()
+                    && let Ok(c) = std::fs::read(full_path.join(atom::LOCK_NAME.as_str()))
+                    && let Ok::<Lockfile, _>(lock) = toml_edit::de::from_slice(c.as_slice())
+                        .map_err(|e| tracing::error!("{}", e))
+                    && let Some(url) = lock.locker().mirror()
+                {
+                    let repo = &cache.to_thread_local();
+                    let mut transport = url.get_transport()?;
+                    let mut remote = repo.ensure_remote(url, &mut transport)?;
+                    let lock_atom = repo.resolve_atom_to_cache(
+                        &mut remote,
+                        lock.locker().label(),
+                        lock.locker().version(),
+                        &mut transport,
+                    )?;
+                    if let Some(entry) = repo
+                        .find_commit(lock_atom.atom)?
+                        .tree()?
+                        .lookup_entry_by_path(NIX_IMPORT_FILE)?
+                    {
+                        std::fs::write(&atom_nix, entry.object()?.detach().data)?;
+                    }
+                }
+                if atom_nix.exists() {
+                    local_atom_dirs.push(full_path.to_path_buf());
+                } else {
+                    tracing::warn!("couldn't resolve lock expression; skipping local atom");
+                }
+            };
+        } else {
+            // TODO: implement setless execution
+            tracing::warn!(
+                label = %uri.label(),
+                "There is no local set established, can't resolve local atom request"
+            );
+        }
+    }
+    tokio::select! {
+        _ = tokio::signal::ctrl_c() => {
+            tasks.shutdown().await;
+        }
+        _ = async {
+            while let Some(dir) = tasks.join_next().await {
+                match dir {
+                    Ok(Some(dir)) => atom_dirs.push(dir),
+                    Err(e) => tracing::error!("{}", e),
+                    _ => {},
+                }
+            }
+        } => {}
+    }
+    let eval_dirs = atom_dirs
+        .iter()
+        .map(|d| d.as_ref().to_path_buf())
+        .chain(local_atom_dirs)
+        .collect::<Vec<_>>();
+    plan_atoms(eval_dirs, context, eval_tmp, platforms).await
+}
+
+async fn plan_atoms_with_shared_context(
+    bin: PathBuf,
+    workdir: impl AsRef<Path>,
+    atom_dirs: Vec<PathBuf>,
+    env: HashMap<String, String>,
+    args: impl IntoIterator<Item = String>,
+) -> io::Result<ExitStatus> {
+    tokio::process::Command::new(&bin)
+        .arg0(crate::NIXEC)
+        .env_clear()
+        .envs(&env)
+        .current_dir(&workdir)
+        .kill_on_drop(true)
+        .args(
+            atom_dirs
+                .iter()
+                .map(|p| {
+                    p.strip_prefix(workdir.as_ref())
+                        .unwrap_or(p.as_ref())
+                        .join(git::NIX_IMPORT_FILE)
+                        .to_string_lossy()
+                        .into_owned()
+                })
+                .chain(args),
+        )
+        .spawn()?
+        .wait()
+        .await
+}
+
+async fn plan_atoms(
+    atom_dirs: Vec<PathBuf>,
+    shared_context: bool,
+    workdir: TempDir,
+    platforms: config::Platforms<'static>,
+) -> anyhow::Result<()> {
+    let bin = std::env::current_exe()?;
+    if crate::is_same_exe(bin.as_ref())? {
+        let value = serde_json::json!({
+            "platforms": platforms
+        });
+        let config = json_digest::canonical_json(&value)?;
+
+        let args = [
+            "-A",
+            git::NIX_ENTRY_KEY,
+            "--argstr",
+            "config",
+            config.as_str(),
+        ]
+        .map(ToOwned::to_owned);
+
+        let mut tasks = JoinSet::new();
+        let filtered_env: HashMap<String, String> = std::env::vars()
+            .filter(|(k, _)| k == "HOME" || k == "PATH" || k == "XDG_CACHE_HOME")
+            .collect();
+        if shared_context {
+            tasks.spawn(async move {
+                plan_atoms_with_shared_context(bin, workdir, atom_dirs, filtered_env, args).await
+            });
+        } else {
+            for dir in &atom_dirs {
+                let local = &workdir.as_ref().join("local");
+                let local = dir.starts_with(local).then_some(&local);
+                let mut child = tokio::process::Command::new(&bin)
+                    .arg0(crate::NIXEC)
+                    .env_clear()
+                    .envs(&filtered_env)
+                    .current_dir(local.unwrap_or(&dir))
+                    .kill_on_drop(true)
+                    .arg(if let Some(local) = local {
+                        dir.strip_prefix(local)?.join(git::NIX_IMPORT_FILE)
+                    } else {
+                        git::NIX_IMPORT_FILE.into()
+                    })
+                    .args(args.iter().map(|p| p.as_str()))
+                    .spawn()?;
+                tasks.spawn(async move { child.wait().await });
+            }
+        }
+
+        tokio::select! {
+            _ = tokio::signal::ctrl_c() => {
+                tasks.shutdown().await;
+            }
+            _ = async {
+                while let Some(res) = tasks.join_next().await {
+                    match res {
+                        Ok(Ok(s)) => {
+                            if s.success() {
+                                tracing::info!("done: {}", s);
+                            }
+                        },
+                        Ok(Err(ref e)) => tracing::error!("{}", e),
+                        Err(ref e) => tracing::error!("{}", e),
+                    }
+                }
+            } => {
+                tracing::info!("all {} jobs completed", crate::NIXEC);
+            }
+        }
+    } else {
+        return Err(anyhow!(
+            "binary was changed at runtime, not safe to re-exec!"
+        ));
+    };
+    Ok(())
+}
diff --git a/src/lib.rs b/src/lib.rs
index 2337147..9e18992 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2,4 +2,30 @@
 
 #![warn(missing_docs)]
 
+use std::ffi::OsString;
+use std::fs;
+use std::os::unix::fs::MetadataExt;
+use std::sync::OnceLock;
+
 pub mod cli;
+
+/// the name of the nixec target
+pub const NIXEC: &str = "nixec";
+
+static STARTUP_INODE: OnceLock<u64> = OnceLock::new();
+static STARTUP_DEV: OnceLock<u64> = OnceLock::new();
+
+/// record the startup executable to check against later
+pub fn record_startup_exe() -> std::io::Result<OsString> {
+    let path = std::env::current_exe()?;
+    let meta = fs::metadata(&path)?;
+    STARTUP_INODE.get_or_init(|| meta.ino());
+    STARTUP_DEV.get_or_init(|| meta.dev());
+    let arg0 = std::env::args_os().next().unwrap_or(OsString::from("eka"));
+    Ok(arg0)
+}
+
+fn is_same_exe(path: &std::path::Path) -> std::io::Result<bool> {
+    let meta = fs::metadata(path)?;
+    Ok(Some(&meta.ino()) == STARTUP_INODE.get() && Some(&meta.dev()) == STARTUP_DEV.get())
+}
diff --git a/src/main.rs b/src/main.rs
index 09e7bc3..ac16fb8 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -2,8 +2,10 @@
 
 #![warn(missing_docs)]
 
+use std::path::PathBuf;
 use std::process::ExitCode;
 
+use anyhow::Context;
 use clap::Parser;
 use eka::cli::{self, Args};
 
@@ -11,18 +13,50 @@ use eka::cli::{self, Args};
 // Functions
 //================================================================================================
 
+fn main() -> ExitCode {
+    let bin = match eka::record_startup_exe().context("could not determine binary info") {
+        Ok(p) => p,
+        Err(e) => {
+            eprintln!("{}", e);
+            return ExitCode::FAILURE;
+        },
+    };
+    match PathBuf::from(bin).file_stem().and_then(|p| p.to_str()) {
+        Some(eka::NIXEC) => nixec(),
+        _ => eka(),
+    }
+}
+
 /// The main entry point for the Eka CLI.
 #[tokio::main]
-async fn main() -> ExitCode {
+async fn eka() -> ExitCode {
     let args = Args::parse_from(cli::change_directory());
     let Args { log, .. } = args;
 
     let _guard = cli::init_global_subscriber(log);
 
-    if let Err(e) = cli::run(args).await {
-        eka::fatal!(e);
-        ExitCode::FAILURE
-    } else {
-        ExitCode::SUCCESS
+    tokio::select! {
+        _ = tokio::signal::ctrl_c() => {
+            tracing::warn!("Ctrl+C received, terminating...");
+            ExitCode::SUCCESS
+        }
+        res = cli::run(args) => {
+            if let Err(e) = res {
+                eka::fatal!(e);
+                ExitCode::FAILURE
+            } else {
+                ExitCode::SUCCESS
+            }
+        }
+    }
+}
+
+fn nixec() -> ExitCode {
+    match nixec::main() {
+        Ok(status) => status,
+        Err(e) => {
+            eprintln!("{}", e);
+            ExitCode::FAILURE
+        },
     }
 }