Enforcement Policies

Relevant source files

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

• src/config.rs
• src/executor.rs
• src/init.rs
• src/main.rs
• README.md

Enforcement Policies in cargo-cooldown define the behavioral constraints applied when the system encounters "fresh" registry crate versions—releases that have not yet exceeded the user-defined cooldown period. These policies determine whether the execution should strictly block fresh versions, allow them with warnings if Cargo requires them, or bypass checks entirely. Sources: src/config.rs:18-22, README.md:52-60

The enforcement mechanism works in tandem with the lockfile_baseline setting to manage the transition from Cargo's resolved graph to a "cooled" graph that prioritizes supply-chain security without breaking dependency validity. Sources: src/executor.rs:271-286, README.md:80-87

Core Enforcement Modes

The system supports three primary enforcement levels, managed via the Enforcement enum. These modes dictate the final outcome of a pinning flow after the batch solver has attempted to find older, Cargo-valid assignments. Sources: src/config.rs:24-34, src/executor.rs:324-341

Mode	Description	Behavioral Outcome
Strict	High-security policy.	Fails the command and restores the original Cargo.lock if any fresh version remains after cooling.
CargoCompatible	Flexible/Warning-based policy.	Allows fresh versions to remain if Cargo requires them, but emits warnings and may require user confirmation.
Off	Bypass mode.	Disables cooldown inspections and pinning logic entirely.

Sources: src/config.rs:24-34, README.md:80-87

Strict Enforcement

Under Strict enforcement, the system adopts a fail-closed posture. If the executor identifies crates that remain "fresh" and cannot be replaced by older versions (due to semver constraints or exact requirements), it triggers an error. This restores the initial lockfile state to ensure no fresh code is consumed. Sources: src/executor.rs:325-337, README.md:89-94

Cargo Compatible Enforcement

The CargoCompatible mode is the default and provides a balance between security and project stability. It attempts to cool every package possible; if a fresh version must remain because no valid older version satisfies the dependency graph, the system proceeds but warns the user. Sources: src/executor.rs:343-353, README.md:97-101

Acceptance Policies

When enforcement is set to cargo_compatible, the CargoCompatibleAccept policy determines how the system handles the remaining fresh versions. Sources: src/config.rs:43-47

• Prompt: The default behavior. If fresh versions remain, the system prints a list of these versions and their publication dates, then waits for interactive user confirmation before proceeding. Sources: src/executor.rs:360-388, src/config.rs:175-180
• Auto: Non-interactive behavior. The system automatically accepts the best Cargo-valid lockfile (even with fresh versions) and continues without waiting for user input. Sources: src/config.rs:48-58, src/executor.rs:345-349

Acceptance Logic Flow

The following diagram illustrates how the system decides whether to continue when fresh versions persist after the cooling phase:

Explanation: This flowchart represents the terminal logic in emit_final_run_summary and confirm_cargo_compatible_fresh_versions. Sources: src/executor.rs:260-286, src/executor.rs:343-393

Policy Configuration and Precedence

Policies are resolved through a layered configuration system. The MergedConfig struct handles the application of these settings from files and environment variables. Sources: src/config.rs:88-100

1. Environment Variables: Overrides all other settings (e.g., COOLDOWN_ENFORCEMENT).
2. Member cooldown.toml: Specific to a workspace member when targeted.
3. Workspace cooldown.toml: Project-wide defaults.
4. Global $CARGO_HOME/cooldown.toml: User-wide defaults.

Sources: src/config.rs:104-120, README.md:72-78

Configuration Data Structures

Explanation: This diagram shows the relationship between the main Config struct and the policy-defining enums. Sources: src/config.rs:24-34, src/config.rs:43-58, src/config.rs:69-82

Implementation Details

The enforcement check is performed at the end of the pinning flow. The system generates a FinalFreshReport containing baseline_fresh and resolver_constrained_fresh versions. Sources: src/executor.rs:260-270

// src/executor.rs:325-333
fn enforce_final_report_policy(enforcement: Enforcement, report: &FinalFreshReport) -> Result<()> {
    if matches!(enforcement, Enforcement::Strict) && !report.resolver_constrained_fresh.is_empty() {
        bail!(
            "strict enforcement blocked fresh versions that could not be cooled further:\n{}\n\n\
             These versions are still inside the configured cooldown window...",
            format_fresh_notice_list(&report.resolver_constrained_fresh).join("\n")
        );
    }
    Ok(())
}

Policy Interactions with Baseline

The lockfile_baseline setting (either floor or ignore) restricts the candidates available to the resolver before the enforcement policy is even evaluated. Sources: src/executor.rs:1134-1148, README.md:104-111

Baseline Setting	Impact on Enforcement
floor	Cooldown cannot downgrade versions below what was in the initial Cargo.lock. Enforcement only applies to new fresh versions.
ignore	Cooldown can downgrade any version. Enforcement applies to any fresh version in the final graph.

Sources: src/config.rs:59-67, README.md:104-111

Conclusion

Enforcement policies provide the final gatekeeping mechanism for the cargo-cooldown system. By choosing between Strict and CargoCompatible modes, developers can define whether their projects should fail-fast on fresh dependencies or provide a flexible path that prioritizes Cargo's resolution requirements while still identifying and warning about potential supply-chain risks. Sources: src/executor.rs:410-424, README.md:162-165