I recently migrated our team from a legacy Yarn/npm setup to pnpm, and the process forced me to confront something I'd heard of but never actually used: lock files. Sure, I'd seen package-lock.json files in repos before—sometimes committed, often ignored, usually treated as mysterious auto-generated noise—but I never understood why they mattered. They were just annoying merge-conflict generators, or so I thought, until modern package managers revealed them as the silent guardians of reproducible builds.

In this article, I'll focus on lock files specifically—what they actually do, why they matter, and how tools like pnpm and Bun handle them. But first, let's look at a scenario that probably feels familiar if you've worked on a team:

You push code on Tuesday. GitHub Actions runs green. You merge to main, deploy to staging, and go home. Wednesday morning, a teammate pulls the latest main, runs pnpm install, and the build explodes. TypeError: generateText is not a function deep in the AI SDK stack. But the CI passed. The package.json is identical. You are running the same commit hash, yet you are running different software.

This is the lock file gap in action. CI pulled dependencies on Tuesday when [email protected] was latest. Your teammate pulled on Wednesday when 6.0.79 had just dropped—a new version that refined an experimental API you were testing. Without a lock file, you are not collaborating on code. You are collaborating on hope.

The Approximation Problem

When you declare "ai-sdk": "^6.0.0" in your package.json, you are not specifying a specific software. You are specifying a range—anything from 6.0.0 up to (but not including) 7.0.0. The caret (^) is a wildcard that accepts new features and patches automatically.

This creates three distinct failure modes in modern development:

• Temporal Drift: Developer A installs on Tuesday and gets [email protected]. Developer B installs Wednesday and gets 6.0.79. You had adopted an experimental provider interface that was still stabilizing—a new streaming utility you were eager to try—and the contract shifted subtly between versions. Your implementations now diverge even though package.json never changed, not due to any fault in the library, but because you were operating on the cutting edge where interfaces are fluid by design.
• Transitive Infection: Your direct dependencies have dependencies. If you depend on Package A, and Package A depends on Package B ^1.2.0, you inherit Package B's volatility. Two team members might have different versions of Package B even though their package.json files are byte-for-byte identical. You are debugging ghosts.
• Supply Chain Roulette: Without cryptographic verification, you trust that 6.0.79 on Tuesday is the same bits as 6.0.79 on Wednesday. If a maintainer re-publishes a version (possible on some registries before integrity checks) or if a man-in-the-middle attack compromises your network, you install compromised code silently.

What the Lock File Actually Contains

A lock file is not a summary. It is a complete ledger—every direct dependency, every transitive dependency, every version resolution, and every cryptographic fingerprint of the exact bytes you approved.

Let us look at a real example from a pnpm-lock.yaml using the AI SDK:

.:
  dependencies:
    '@ai-sdk/react':
      specifier: ^3.0.3
      version: 3.0.80([email protected])([email protected])

Notice the distinction between specifier and version. Your package.json requested ^3.0.3—anything from 3.0.3 up to 4.0.0. The lock file captured the exact resolution: 3.0.80. It also recorded the precise versions of peer dependencies that were present at install time ([email protected], [email protected]).

Now look deeper at the package definition:

packages:
...
'@ai-sdk/[email protected]':
  resolution: {integrity: sha512-ERdj1fxRYiYX2xyy2lIahdcnrdbZ5/Xi/LSFiCU6wGISrFmtYiSkILUaBX4YtDYgqMdRIuyOl9+rkrwwo9l0ZQ==}
  engines: {node: '>=18'}
  peerDependencies:
    react: ^18 || ~19.0.1 || ~19.1.2 || ^19.2.1

The integrity field is a SHA-512 hash of the exact tarball downloaded from npm. This is the cryptographic anchor. When pnpm installs, it computes the hash of the retrieved bytes and compares it to this value. If they do not match—perhaps the maintainer republished the version, or your registry proxy corrupted the download—the install halts with:

ERR_PNPM_CHECKSUM_FAILED: The lockfile entry for "@ai-sdk/[email protected]"
has a conflicting integrity checksum.

Finally, examine the snapshot section: