Coordinated Dependency Bundles

Relevant source files

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

• src/executor.rs
• src/resolution_state.rs
• src/config.rs
• src/init.rs
• README.md
• tests/integration.rs

Coordinated Dependency Bundles represent a specialized resolution strategy within cargo-cooldown designed to handle groups of registry crates that are inextricably linked by exact version requirements. In standard operation, the system attempts to cool dependencies individually; however, some crates (e.g., web-sys, js-sys, and wasm-bindgen) often require identical versions of their siblings to function.

The purpose of this module is to identify these connected components and solve them as a single unit. This prevents the "ping-pong" effect where cooling one crate breaks the exact requirement of another, leading to a resolver failure. By grouping these into a bundle, the system can backtrack through candidate versions in a bounded search space to find a coherent set of versions that satisfy both the cooldown window and internal exact-version constraints.

Architecture and Component Flow

The coordinated resolution process is integrated into the main execution loop as a fallback and optimization mechanism. It operates by analyzing the dependency graph for "exact requirement" edges—specifically semver requirements using the = operator.

Key Data Structures

The system uses several structures to manage the complexity of bundle resolution:

Structure	Description	Source
ConstraintContribution	Records semver requirements and the count of "exact" matches for a child crate.	src/resolution_state.rs:154-160
RequirementOrigin	Tracks which parent crate and specific requirement string constrained a resolved package.	src/resolution_state.rs:80-84
BundleCandidate	Represents a potential version for a bundle member, including its internal requirements.	src/executor.rs:1344-1348
BundleMemberPlan	A collection of safe candidates for a specific crate within a coordinated group.	src/executor.rs:1351-1354

Component Grouping and Constraint Logic

The core logic for bundles relies on the identification of Equality Dependents. During the scan of the dependency graph, cargo-cooldown specifically flags packages that have exact version requirements.

Exact Requirement Identification

A requirement is considered "exact" if it uses the = operator (e.g., =1.2.3). These are treated as hard constraints that must move in unison.
Sources: src/executor.rs:967-975, src/resolution_state.rs:379-384

Component Building

The system builds a graph of "constraint edges" where nodes are fresh crates and edges represent mutual exact requirements. It then extracts "Connected Components" from this graph.

• Size Limits: Coordinated resolution is intentionally narrow. Components exceeding MAX_COORDINATED_COMPONENT_SIZE (currently 8) are skipped to avoid explosive search spaces.
• Candidate Limits: Only MAX_COORDINATED_CANDIDATES (currently 4) are considered per member.
  Sources: src/executor.rs:26-31, src/executor.rs:1402-1438

Backtracking Solver

Once a bundle is identified, the system employs a bounded backtracking search to find a compatible set of versions.

Search Validation

The solver ensures that for every proposed assignment:

1. The version satisfies all External Requirements (those coming from crates outside the bundle).
2. The version satisfies all Internal Requirements (those defined by other bundle members).
3. The version satisfies Baseline Floor constraints if lockfile_baseline = "floor" is configured.
   Sources: src/executor.rs:1463-1481, src/executor.rs:1546-1570

Application and Cargo Validation

After a coordinated assignment is found, the executor attempts to write these pins to the Cargo.lock file. This is a critical step because the local solver only has a partial view of the graph.

1. Lockfile Write: The system rewrites the version and checksum fields for all bundle members in the TOML document.
2. Cargo Metadata Check: Cargo is executed with the --locked flag. If Cargo accepts the manual rewrite, the resolution is successful.
3. Conflict Parsing: If Cargo rejects the assignment, the system parses the error output to identify "Blocker" packages. If the blockers are part of the bundle, the assignment is discarded.
   Sources: src/executor.rs:1722-1772, src/executor.rs:1849-1886

Summary of Resolution Constraints

The behavior of Coordinated Dependency Bundles is modified by the project's cooldown.toml settings.

Configuration	Impact on Bundles
lockfile_baseline = "floor"	Prevents the bundle solver from selecting versions older than those in the initial Cargo.lock.
enforcement = "strict"	If the bundle solver fails to find a valid older set, the entire run fails.
enforcement = "cargo_compatible"	If the solver fails, the fresh versions are kept as "resolver-constrained" and reported as warnings.
Sources: src/config.rs:43-65, README.md:95-104

Coordinated Dependency Bundles ensure that cargo-cooldown remains robust even when faced with the complex, strictly-versioned interdependencies common in the Rust ecosystem. By identifying these clusters and solving them atomically, the tool maintains dependency graph integrity while enforcing security-oriented cooldown periods.