Yarn Berry Cache Configuration for Zero-Installs and Registry Consistency

Targeted Cache Invalidation

To invalidate specific committed cache entries without purging the entire project cache, you must remove the specific zip archives associated with the affected package and force a lockfile update. Because Yarn Berry uses the .yarn/cache directory as the source of truth for Zero-Installs, simply deleting a file is insufficient if the yarn.lock integrity hash remains unchanged.

The recommended workflow for targeted invalidation is:

1. Identify and Remove: Locate and delete the specific .zip archive for the package in .yarn/cache.
2. Force Refresh: Run yarn install. Yarn will detect the missing archive and fetch the current version from the registry.
3. Update Integrity: If the registry artifact has mutated (changing the checksum), Yarn will update the integrity hash in yarn.lock.
4. Commit Together: Commit both the new .zip archive and the updated yarn.lock in a single pull request. This ensures all contributors move to the new artifact simultaneously.

CI Reconciliation and Integrity Hashes

In a standard Zero-Installs CI pipeline, you should run yarn install --immutable. Under this configuration, Yarn does not reconcile a committed cache archive against a modified registry hash; instead, it treats any discrepancy as a failure.

If the committed archive exists but the yarn.lock integrity hash differs from what the registry currently reports, or if the archive is missing but the lockfile expects it, the build will fail. This is a safety feature designed to prevent "poisoned" artifacts or silent mutations from entering the build pipeline. The CI environment is intended to be a consumer of the committed state, not a mechanism for updating it.

Likely Explanation of Registry Conflicts

Conflicts typically arise when a private registry allows "overwriting" a version (e.g., publishing v1.0.1 twice with different code). Since Yarn relies on the version string and the checksum, a mutation without a version bump creates a state where the yarn.lock is technically correct for the old artifact but incorrect for the new one. The only way to resolve this across a distributed team is an intentional update to the lockfile and the committed cache.

Verification Steps

To verify your CI is correctly enforcing integrity, you can perform the following test in a clean environment:

# Attempt an immutable install with a missing or modified cache zip
yarn install --immutable

The command should exit with a non-zero code if the local cache does not perfectly match the lockfile's requirements.

Diagnostic Detail Needed: Please specify your exact Yarn Berry version (e.g., 3.6.4 or 4.x), as checksum enforcement and immutable flag behaviors have evolved across releases.