Merge pull request #23 from ekala-project/dependency-finalization

feat: finalize dependency management

Author: nrdxp

Cargo.lock

@@ -15,6 +15,7 @@ strip         = true
 
 anyhow.workspace             = true
 clap.workspace               = true
+either.workspace             = true
 gix.workspace                = true
 semver.workspace             = true
 tempfile.workspace           = true
@@ -30,6 +31,7 @@ atom.path = "crates/atom"
 
 [workspace.dependencies]
 anyhow            = "^1"
+lazy-regex        = "3.4.1"
 tempfile          = "^3.13"
 thiserror         = "^1"
 tracing           = "^0.1"
@@ -41,6 +43,7 @@ clap = { version = "^4", features = [
   "wrap_help",
   "unstable-markdown",
 ] }
+either = { version = "1.15.0", features = ["serde"] }
 insta = { version = "^1", features = ["yaml"] }
 semver = { version = "^1", features = ["serde"] }
 serde = { version = "^1", features = ["derive"] }

Cargo.toml

@@ -0,0 +1,58 @@
+# 8. Lockfile Data Model and Synchronization Refactor
+
+- **Status:** Proposed
+- **Deciders:** eka-devs
+- **Date:** 2025-10-13
+
+## Context and Problem Statement
+
+The initial implementation of the ADR#7 manifest and lockfile format has revealed several areas of unnecessary complexity and inefficiency in the underlying data models. The primary issues are:
+
+1.  **Redundant Identity Types:** The `lock.rs` module defines an `AtomDigest` struct to represent an atom's cryptographic ID, which is conceptually redundant with the `IdHash` struct defined in the canonical `id` module. This creates a confusing and error-prone translation layer.
+2.  **Inefficient In-Memory Lockfile Structure:** The lockfile is currently deserialized into a `BTreeSet`, which requires inefficient linear scans for lookups and updates. This data structure will not scale and makes implementing future features, like transitive dependency resolution, overly complex.
+3.  **Complex Synchronization Logic:** The existing synchronization logic is difficult to implement and maintain due to the inefficient data structures and redundant types.
+
+This ADR proposes a refactoring of the core data models to address these issues, creating a more elegant, efficient, and robust system for managing lockfiles.
+
+## Decision
+
+We will refactor the core identity types and the in-memory representation of the lockfile. The implementation will be conducted in three phases.
+
+### Phase 1: Refactor Core Identity Types
+
+The goal of this phase is to create a single, canonical representation for an atom's cryptographic ID.
+
+- **Step 1.1:** In `crates/atom/src/id/mod.rs`, the ephemeral `IdHash` struct will be renamed to `IdHashView` to clarify its purpose as a temporary, referenced view of a hash.
+- **Step 1.2:** A new public, storable struct, `pub struct Id([u8; 32]);`, will be created in `crates/atom/src/id/mod.rs`. This will become the canonical, owned type for an atom's cryptographic ID.
+- **Step 1.3:** The `AtomId::compute_hash()` method will be modified to return this new `id::Id` struct.
+- **Step 1.4:** The redundant `AtomDigest` struct will be completely removed from `crates/atom/src/lock.rs`.
+- **Step 1.5:** The `AtomDep` struct in `crates/atom/src/lock.rs` will be updated to use the new `id::Id` for its `id` field.
+
+### Phase 2: Redesign In-Memory Lockfile Structure
+
+This phase will optimize the in-memory data structure for the lockfile for efficient lookups.
+
+- **Step 2.1:** The `Lockfile` struct in `crates/atom/src/lock.rs` will be modified. The `DepMap` (a `BTreeSet`) will be replaced with separate `BTreeMap` collections for each major dependency type.
+- **Step 2.2:** The primary map will be `atoms: BTreeMap<id::Id, AtomDep>`, providing efficient O(log n) lookups. Similar maps will be added for Nix dependencies, keyed by their `Name`.
+- **Step 2.3:** Custom `Serialize` and `Deserialize` implementations for the `Lockfile` struct will be created to handle the conversion between the efficient in-memory `BTreeMap` representation and the readable on-disk flat list of `[[input]]` tables.
+
+### Phase 3: Implement the New Synchronization Algorithm
+
+With the new data models in place, we will implement a clear and robust synchronization algorithm.
+
+- **Step 3.1:** Implement the loading logic to parse `atom.toml` and deserialize `atom.lock` into the new `BTreeMap`-based `Lockfile` structure.
+- **Step 3.2:** Implement the reconciliation logic. This will iterate through manifest dependencies, compute the expected `id::Id` for each, and use the `BTreeMap` for efficient lookups to add, update, or verify entries against the loaded lockfile.
+- **Step 3.3:** Implement pruning logic to remove any stale entries from the lockfile that are no longer present in the manifest.
+- **Step 3.4:** Implement the final write logic that serializes the in-memory `Lockfile` back to the `atom.lock` on-disk format.
+
+## Consequences
+
+- **Positive:**
+
+  - **Reduced Complexity:** Eliminates redundant types and simplifies the conceptual model.
+  - **Improved Performance:** The `BTreeMap` structure provides efficient lookups, making the system more scalable.
+  - **Increased Robustness:** A clearer data model and algorithm will be less prone to bugs and easier to maintain.
+  - **Future-Proofing:** Provides a solid foundation for future features like transitive dependency resolution.
+
+- **Negative:**
+  - **Implementation Effort:** This is a significant refactoring that will require careful implementation and testing.

adrs/0008-lockfile-refactor.md

@@ -12,6 +12,8 @@ nom               = "^7"
 path-clean        = "^1"
 unic-ucd-category = "^0.9"
 
+either.workspace            = true
+lazy-regex.workspace        = true
 prodash.workspace           = true
 semver.workspace            = true
 serde.workspace             = true

crates/atom/Cargo.toml

@@ -4,18 +4,24 @@
 //! file system structure. These types form the foundation of the atom format
 //! and are used throughout the crate.
 
+use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 
 use semver::Version;
 use serde::{Deserialize, Serialize};
 
-use super::id::AtomTag;
+use super::id::{AtomTag, Name};
+use crate::manifest::AtomSets;
+
+//================================================================================================
+// Types
+//================================================================================================
 
 /// Represents the deserialized form of an Atom, directly constructed from the TOML manifest.
 ///
 /// This struct contains the basic metadata of an Atom but lacks the context-specific
 /// [`crate::AtomId`], which must be constructed separately.
-#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Atom {
     /// The verified, human-readable Unicode identifier for the Atom.
@@ -27,6 +33,10 @@ pub struct Atom {
     /// An optional description of the Atom.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub description: Option<String>,
+
+    /// A table of named atom sets, defining the sources for resolving atom dependencies.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub sets: HashMap<Name, AtomSets>,
 }
 
 /// Represents the file system paths associated with an atom.
@@ -45,6 +55,10 @@ where
     content: P,
 }
 
+//================================================================================================
+// Impls
+//================================================================================================
+
 impl AtomPaths<PathBuf> {
     /// Creates a new `AtomPaths` instance from a given path.
     ///