[zkochan]

Summary

Proposes the next lockfile format. packages has one entry per package, keyed by name@version, holding its metadata, its resolved dependencies, and its peer bindings as properties: peers for the package's own, transitivePeers for those bound below it. There is no snapshots section, and no key or reference carries a peer or patch group: the patch hash lives in patchedDependencies, and a reference the referrer's scope does not select names its snapshot by its peer bindings. peerDependenciesMeta is folded into peerDependencies: an optional peer is {specifier: '*', optional: true} on one line. An importer's dependency is its specifier alone when the version follows from it, and {specifier, version} on one line otherwise. A package installed with several sets of peers has one snapshot per set. The entry writes what the snapshots share once and lists what differs under snapshots. A reference names a version, and the referrer's bindings select the snapshot; where they can't, the reference keeps its peer groups.

The RFC also requires every directory package's entry to record specifiers, the field pnpm/pnpm#17477 adds to lockfile 9.0 as optional.

It fixes these problems:

• The peer suffix is repeated at every reference, so a provider bump rewrites every key and reference that embeds it. In chore: update dependencies, Node.js, pnpm, and GitHub Actions pnpm#17773, 139 of the 309 changed lines are such renames, and 13 mention the package that changed.
• A clean git merge can produce a broken lockfile, when one branch renames a snapshot and another adds a reference to the old key.
• A resolved optional peer is recorded under the snapshot's optionalDependencies, as if the package declared an optional dependency.
• A name that a package declares as both a dependency and a peer is written under dependencies whether a parent provided it or the package's own dependency was installed (Decide peer recording from one function, and test reuse against fresh resolution through the real lockfile writer tasks#221).
• A hashed peer suffix can't be read back from its snapshot, and the search that recovers it is bounded.
• transitivePeerDependencies lists resolved and missing peers together.
• A directory package records its resolved children but not the specifiers they were resolved from, so the frozen-lockfile check resolves them again (Record a directory package's specifiers in the lockfile and make the frozen check an equality tasks#228).

A prototype in pnpm v12 (pnpm/pnpm#17886), behind a lockfile.format: next setting, reads and writes 170 of 173 real lockfiles exactly. A 5,623-snapshot lockfile goes from 4.40 MB to 2.20 MB and from 99,955 lines to 58,186, and a react bump changes 58 lines instead of 142. On a 237-project workspace, installs are within noise of today's format except regenerating a deleted pnpm-lock.yaml, which pays the prototype's write cost (+6 to +12 ms). The "Prototype results" section has the numbers and what the design had to change: references keep their peer groups where the referrer's scope doesn't predict the snapshot, and peers bound from anywhere in the graph go in missingPeers. The section also splits the prototype's time into the stages the format needs and the stages only its conversion needs, as an estimate for the native implementation planned for pnpm v13.

The earlier drafts, which kept the suffix keys, and the designs considered on the way (ordinal ids, grouping by suffix, keys by peer names) are listed as alternatives with the reasons they fall short. The lockfileVersion number is left open, given the decision recorded in #68.

---

Written by an agent (Claude Code, claude-fable-5-1).

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[zkochan]

The prototype described under "Prototype results" is open as a draft: pnpm/pnpm#17886. It is opt-in, behind lockfile.format: next.

---

Written by an agent (Claude Code, claude-opus-5-5).