Lockfile & Content Addressing

Relevant source files

The following files were used as context for generating this wiki page:

• src/state/lockfile.rs
• src/core/integrity.rs
• README.md
• AGENTS.md
• CONTRIBUTING.md
• src/util/fs_safety.rs

Numan utilizes a structured lockfile and content-addressed payload system to ensure reproducibility, artifact integrity, and platform safety. The lockfile serves as the "ground truth" for all installed packages, pinning specific versions, payload hashes, and install origins to prevent silent drift or unauthorized modifications.

The system is built on the principle of immutability. Once an artifact is installed, it is placed in a versioned, content-addressed path within the Numan root. This ensures that updates do not overwrite existing files in place, allowing for reliable rollbacks and parallel installations of different package versions.

Sources: README.md:12-25, AGENTS.md:113-116, CONTRIBUTING.md:105-110

Lockfile Architecture

The Numan lockfile (Lockfile v2) is the authoritative record of the system state. It tracks installed packages, their specific versions, and their activation status within Nushell.

Lockfile Structure and Components

The lockfile manages two primary types of activation records: PluginActivation and ModuleActivation. These records ensure that a package is only considered "active" if it matches the current environment (Nu version and executable hash).

Key Data Fields

Field	Description	Source
origin	The source registry or URL from which the package was installed.	README.md:20
revision_id	A unique identifier for the current lockfile state, used for change detection.	src/state/lockfile.rs:15
payload_sha256	The SHA256 hash of the installed payload for integrity verification.	src/state/lockfile.rs:18
nu_executable_sha256	Pins a plugin activation to a specific Nushell binary hash.	AGENTS.md:143

Content Addressing and Immutability

Numan enforces an immutable payload structure where installs land under versioned, content-addressed paths. This prevents overwriting foreign files and ensures that the system can always verify the integrity of installed artifacts.

Payload Path Structure

Payloads are stored in a specific directory hierarchy based on the package type, owner, and a unique hash prefix:
$NUMAN_ROOT/packages/<type>/<owner>/<name>/<version>-<sha8prefix>/

Sources: AGENTS.md:113-116, README.md:214-220

Integrity Verification

Mandatory SHA256 verification is performed for all plugin binaries during the install transaction. The system computes the hash of the downloaded artifact and compares it against the expected hash recorded in the registry and subsequent lockfile.

Mutation Serialization

To prevent corruption and partial writes, Numan utilizes advisory filesystem locks and atomic JSON writes.

The Mutation Lock

All mutating commands—including install, remove, update, and gc—must acquire an exclusive advisory lock on $NUMAN_ROOT/state/mutation.lock. This prevents concurrent Numan processes from interleaving destructive operations on the same root.

// src/util/fs_safety.rs:48-60
pub fn acquire_mutation_lock(root: &Path) -> Result<MutationLock> {
    let lock_path = root.join("state").join("mutation.lock");
    let file = std::fs::OpenOptions::new()
        .read(true).write(true).create(true)
        .open(&lock_path)?;
    // ... logic for non-blocking exclusive lock ...
}

Sources: src/util/fs_safety.rs:40-75, CONTRIBUTING.md:109, REVIEW.md:29

Atomic Operations

State changes are written using write_json_atomic, which involves writing to a temporary file in the same directory and then persisting it via an OS-atomic move. This ensures that files like the lockfile or journals are never left in a partially written or corrupted state.

Sources: src/util/fs_safety.rs:18-25, AGENTS.md:154-156, REVIEW.md:30

Conclusion

The combination of a strict Lockfile v2 and content-addressed payloads provides a robust foundation for Numan's package management. By treating the lockfile as the ground truth and enforcing immutable storage patterns, the system achieves predictable behavior across different environments and Nushell versions.

Sources: AGENTS.md:139-140, README.md:243-248