Lockfile Baseline Policies

Relevant source files

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

• src/config.rs
• src/lockfile.rs
• src/executor.rs
• src/init.rs
• README.md
• src/isolation.rs

Lockfile Baseline Policies in cargo-cooldown define how the system treats registry crate versions that already exist in the user's Cargo.lock before a command is executed. These policies determine whether the current state of the lockfile acts as a "floor" for dependency versions or if the tool is permitted to downgrade dependencies below their currently locked versions to satisfy cooldown requirements.

The core of this system is the lockfile_baseline configuration, which interacts with the execution flow to protect users from accidental downgrades of established dependencies while ensuring that new updates adhere to configured age restrictions. Sources: src/lockfile.rs:1-8, README.md:54-60

Baseline Modes

The project supports two primary modes for handling the lockfile baseline: floor and ignore.

Mode	Description	Default
floor	Uses versions in the initial Cargo.lock as a minimum version floor. Cooldown will not downgrade established versions even if they are "fresh".	Yes
ignore	Allows cooldown to downgrade established registry packages to older versions if the currently locked versions are too fresh.	No

Sources: src/config.rs:62-75, src/init.rs:188-196, README.md:73-83

Floor Mode Logic

In floor mode, cargo-cooldown treats the pre-run lockfile as a protection layer. It ensures that the resolver never writes a lockfile that Cargo would reject, but specifically prevents moving to a version lower than what was already established. Sources: src/lockfile.rs:114-118, README.md:65-68

Ignore Mode Logic

In ignore mode, the tool tries to cool every eligible locked registry package. This includes versions that were already present before the run. This is useful when a user wants to proactively downgrade recently added dependencies that haven't yet met the age requirement. Sources: README.md:79-81, tests/integration.rs:121-125

Architectural Components

The baseline policy is implemented through several key data structures and modules that handle snapshotting, indexing, and comparison.

LockfileSnapshot and LockfileBaseline

The LockfileSnapshot captures the state of the lockfile at the start of execution. It contains a LockfileBaseline index, which maps crate names and registries to their respective versions.

The baseline index allows for O(log n) lookups of the version floor for any given package. Sources: src/lockfile.rs:20-30, src/lockfile.rs:73-80, src/lockfile.rs:136-138

Execution Flow

The executor module utilizes the baseline during the pinning flow to filter candidates.

Policy Enforcement Interaction

Baseline policies work in tandem with the enforcement setting to determine the final outcome if Cargo requires a fresh version that cannot be cooled.

• Floor + Strict: Fail and restore the original Cargo.lock if any fresh version remains that wasn't already in the baseline.
• Ignore + Strict: Fail if any fresh version (including established ones) cannot be cooled.
• Floor + CargoCompatible: Keep the best Cargo-valid lockfile (respecting the floor), and warn about remaining fresh versions.

Sources: README.md:73-83, src/executor.rs:277-290

Implementation Details

Capturing the Baseline

The baseline is indexed by parsing the Cargo.lock into a LockfileBaseline struct. Only registry sources are tracked; workspace members and path dependencies are excluded from the version floor.

// src/lockfile.rs:81-104
for package in lockfile.package {
    let Some(source_id) = package.source else { continue; };
    if !is_registry_source(&source_id) { continue; }

    let registry = registry_store.context_for_source(&source_id)?.effective_index_url.clone();
    let name = package.name;
    let version = package.version;

    if let Ok(parsed_version) = Version::parse(&version) {
        versions_by_package
            .entry(name.clone())
            .or_insert_with(BTreeMap::new)
            .entry(registry.clone())
            .or_insert_with(Vec::new)
            .push(parsed_version);
    }
    packages.insert(LockfilePackageKey { name, registry, version });
}

Sources: src/lockfile.rs:81-104

Calculating the Version Floor

When determining a candidate for a package, the system checks the baseline to find the newest version that is not greater than the current candidate version. This becomes the GreaterEq requirement in the resolver. Sources: src/executor.rs:1066-1080, src/lockfile.rs:125-139

Configuration Options

Users can configure baseline policies via environment variables or cooldown.toml.

Config Key	Env Variable	Valid Values	Description
lockfile_baseline	COOLDOWN_LOCKFILE_BASELINE	floor, ignore	Controls version floor behavior.

Sources: src/config.rs:200-202, src/init.rs:319-325

Summary

Lockfile Baseline Policies provide a safety mechanism to prevent cargo-cooldown from inadvertently regressing a project's dependency state. By defaulting to floor mode, the system respects the developer's existing Cargo.lock while still applying age-based "cooldown" restrictions to any new or updated dependencies. Users requiring more aggressive cooling of already-locked packages can opt into ignore mode to allow downgrades of established but "fresh" crates. Sources: README.md:54-68, src/executor.rs:67-75