Walkthrough

This PR runs lockfile verification concurrently with fetch/link during frozen installs, gates lifecycle scripts and final success on verification passing, adds a pnpr verification-only endpoint and client method, and threads verification overrides and tarball prefetching into pacquet's frozen-install fast path.

Changes

Concurrent Lockfile Verification

Sequence Diagram(s)

sequenceDiagram
  participant CLI as pacquet CLI
  participant PnprClient as PnprClient
  participant Server as pnpr Server
  participant Resolver as Resolver
  participant Installer as Install/FrozenInstall
  CLI->>PnprClient: request verify_lockfile (VerifyLockfileOptions)
  PnprClient->>Server: POST /v1/verify-lockfile
  Server->>Resolver: handle_verify_lockfile(body)
  Resolver-->>PnprClient: terminal NDJSON frame (done|violations|error)
  CLI->>Installer: run frozen Install (with optional override)
  Installer->>Verifier: await verifyLockfile callback before lifecycle

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

• Cache lookup opens a fresh SQLite connection per snapshot; per-file stat storm on every install pacquet#260: Adds batched store-index probes and prefetch filtering—related to StoreIndex::contains_many and prefetch_lockfile.
• pacquet: port lockfile verification (minimumReleaseAge + trustPolicy) #11722: Shares lockfile verification gate work and threading verification into install flows.
• Frozen-lockfile freshness check: error when package.json drifts from pnpm-lock.yaml pacquet#447: Related to frozen-install freshness checks and overlapping frozen-path logic.

Possibly related PRs

• pnpm/pnpm#11734: Overlaps frozen-install fast-path and pnpr delegation changes.
• pnpm/pnpm#12245: Touches InstallFrozenLockfile orchestration that this PR modifies.
• pnpm/pnpm#11824: Modifies Install dispatch/verification decision points related to this work.

Poem

🐰 I started a race with a lockfile today,

verification hummed while downloads stayed away,
scripts sat quiet till the verdict came through,
if it failed we stopped — if it passed we grew,
modules linked snug — a hop, and we're new.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

• X
• Mastodon
• Reddit
• LinkedIn

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Description

TarballPrefetcher::prefetch_lockfile prefetches every Registry resolution in lockfile.packages
without applying the frozen install’s dependency-group/skip filters, so it can download tarballs for
packages that InstallFrozenLockfile will never materialize (e.g. optional deps excluded by flags).
This creates avoidable network/store churn and can slow down or stress registries on large
lockfiles.

Code

pacquet/crates/package-manager/src/tarball_prefetch.rs[R294-320]

+    pub async fn prefetch_lockfile(&self, lockfile: &Lockfile, config: &Config) {
+        let Some(packages) = lockfile.packages.as_ref() else {
+            return;
+        };
+        let mut pending = Vec::with_capacity(packages.len());
+        for (package_key, metadata) in packages {
+            if !matches!(&metadata.resolution, LockfileResolution::Registry(_)) {
+                continue;
+            }
+            let (tarball_url, integrity) =
+                tarball_url_and_integrity(&metadata.resolution, package_key, config)
+                    .expect("registry resolutions always carry an integrity");
+            let package_id = package_key.without_peer().to_string();
+            let integrity = integrity.to_string();
+            pending.push(PendingPrefetch {
+                store_key: store_index_key(&integrity, &package_id),
+                package_id,
+                package_url: tarball_url.into_owned(),
+                integrity,
+            });
+        }
+        for entry in without_store_hits(self.store_index.clone(), pending).await {
+            let PendingPrefetch { package_id, package_url, integrity, .. } = entry;
+            // The lockfile records no dist size hints, so the downloads
+            // queue without a work estimate.
+            self.prefetch(package_id, package_url, &integrity, None, None);
+        }

Evidence

prefetch_lockfile walks lockfile.packages and schedules downloads for every registry resolution. The
frozen install path explicitly excludes optional snapshots (and other skipped categories) and passes
the skip set down into CreateVirtualStore, so some prefetched entries are guaranteed to never be
used.

pacquet/crates/package-manager/src/tarball_prefetch.rs[279-321]
pacquet/crates/package-manager/src/install_frozen_lockfile.rs[452-480]
pacquet/crates/package-manager/src/install_frozen_lockfile.rs[656-670]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`TarballPrefetcher::prefetch_lockfile()` currently iterates over **all** `lockfile.packages` registry entries and schedules downloads, but the frozen install pipeline later filters the graph (e.g. `--no-optional`, runtime skipping, installability skips) via a `skipped` set. This means the prefetch phase can download tarballs for packages that will never be linked/built in this invocation.
### Issue Context
- Frozen installs compute a `skipped` set based on `dependency_groups` and other flags and pass it into `CreateVirtualStore`.
- The new prefetcher runs before that filtering and has no knowledge of which snapshots will be materialized.
### Fix Focus Areas
- pacquet/crates/package-manager/src/tarball_prefetch.rs[279-321]
- pacquet/crates/package-manager/src/install_frozen_lockfile.rs[452-480]
- pacquet/crates/package-manager/src/install_frozen_lockfile.rs[656-670]
### Suggested fix
Refactor `prefetch_lockfile` (or add a new method) to prefetch only the subset of packages that the frozen install will actually materialize:
1. Prefer driving prefetch from `lockfile.snapshots` + the already-computed `skipped` set (and dependency-group reachability), rather than `lockfile.packages`.
2. Alternatively, move the prefetch kickoff into `InstallFrozenLockfile::run` *after* `skipped` is computed, so it can prefetch only non-skipped snapshot keys.
3. Keep the existing store-index hit filtering to avoid redundant downloads.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

In mutateModules, settleInstall() throws as soon as lockfile verification fails but does not
cancel the already-started _install() promise, so fetch/link work may continue mutating the
store/node_modules after the caller has already observed failure. This is especially risky for
programmatic/long-lived callers because the background install can overlap subsequent operations and
still perform filesystem/network I/O despite the reported failure.

Code

installing/deps-installer/src/install/index.ts[R540-555]

+  async function settleInstall (
+    install: Promise<InnerInstallResult>,
+    verification: Promise<void> | undefined
+  ): Promise<InnerInstallResult> {
+    if (verification == null) return install
+    // Handle the install's eventual rejection up front so a fail-fast
+    // verification throw below doesn't leave the still-running install
+    // unhandled.
+    install.catch(() => {})
+    try {
+      await verification
+      return await install
+    } catch (err) {
+      detachReporter()
+      throw err
+    }

Evidence

_install() is started immediately and settleInstall() only awaits the verification verdict
before throwing; there is no abort/cancel mechanism invoked, so the in-flight install continues. The
only explicit verification gate shown is immediately before buildModules, meaning earlier install
phases can run even after verification has failed.

installing/deps-installer/src/install/index.ts[404-412]
installing/deps-installer/src/install/index.ts[465-556]
installing/deps-restorer/src/index.ts[583-606]
installing/deps-installer/src/install/index.ts[1671-1674]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`settleInstall()` fails fast on lockfile verification failure, but it cannot actually stop the already-started `_install()` work. This means the command/API may return a verification error while `_install()` continues doing I/O and filesystem mutations in the background.
### Issue Context
- Verification is kicked off early and `_install()` is started immediately (`settleInstall(_install(), verifyLockfilePromise)`).
- Dependency lifecycle scripts are gated via `await opts.verifyLockfile?.()` right before `buildModules`, but fetch/link phases can still run after verification has failed, until they naturally reach a gate or complete.
### Fix Focus Areas
- installing/deps-installer/src/install/index.ts[404-412]
- installing/deps-installer/src/install/index.ts[465-556]
- installing/deps-restorer/src/index.ts[583-606]
- installing/deps-installer/src/install/index.ts[1671-1674]
### Suggested fix
Implement cooperative cancellation for the install pipeline:
1. Create an `AbortController`/cancellation token in `mutateModules` when starting concurrent verification.
2. Attach a handler to the verification promise that triggers cancellation on failure.
3. Thread the abort signal/token into the parts of `_install()` that perform long-running work (fetching/linking) and make them bail out early when cancelled.
4. Ensure cancellation is also triggered when `mutateModules` exits early (e.g., preResolution hooks throw) to avoid leaving verification/fetch work running in the background.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

In pacquet’s frozen pnpr restore fast-path, prefetcher.shutdown().await is only executed on
success; any install/verification error triggers an early return via ? and skips the
shutdown/flush. This can drop the chance to drain/flush the store-index writer task and may leave
background work unfinished when the command exits.

Code

pacquet/crates/cli/src/cli_args/install.rs[R581-593]

+        let result = match lockfile_verification_override {
+            Some(lockfile_verification_override) => {
+                install
+                    .run_with_lockfile_verification::<Reporter>(lockfile_verification_override)
+                    .await
+            }
+            None => install.run::<Reporter>().await,
+        };
+        result.wrap_err("restoring dependencies from the local lockfile via pnpr verification")?;
+
+        prefetcher.shutdown().await;
+
+        return Ok(());

Evidence

The CLI path uses result.wrap_err(...)?; before prefetcher.shutdown().await, so errors bypass
shutdown. The prefetcher shutdown docs and store-index writer docs indicate the writer task should
be awaited after dropping the last sender so the final batch flushes.

pacquet/crates/cli/src/cli_args/install.rs[521-593]
pacquet/crates/package-manager/src/tarball_prefetch.rs[264-286]
pacquet/crates/store-dir/src/store_index.rs[111-116]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The frozen pnpr restore path creates a `TarballPrefetcher` but calls `prefetcher.shutdown().await` only after `result.wrap_err(...)?` succeeds. On any error, the `?` returns early and skips shutdown, even though the prefetcher’s writer task is documented as requiring an explicit drain/await to flush the final batch.
### Issue Context
`TarballPrefetcher::shutdown(self)` drops the writer handle and awaits the writer task to flush queued rows. Skipping it on failures makes behavior depend on Drop/runtime shutdown timing.
### Fix Focus Areas
- pacquet/crates/cli/src/cli_args/install.rs[521-593]
- pacquet/crates/package-manager/src/tarball_prefetch.rs[264-286]
- pacquet/crates/store-dir/src/store_index.rs[111-116]
### Suggested fix
Restructure to always run shutdown before returning:
- Capture `result` (success or error) without `?`.
- Call `prefetcher.shutdown().await` unconditionally.
- Then return `result.wrap_err(...)`.
Example shape:

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

A comment in tryFrozenInstall still claims it mirrors a removed verifyLockfileResolutions try/catch,
which is no longer true after verification was made concurrent; this misleads future maintainers
about why detachReporter is needed there.

Code

installing/deps-installer/src/install/index.ts[R404-412]

+    verifyLockfilePromise = verifyLockfileResolutions(ctx.wantedLockfile, opts.resolutionVerifiers, {
+      cacheDir: opts.cacheDir,
+      lockfilePath: wantedLockfilePath,
+    })
+    // Keep the rejection from going unhandled in the window before
+    // `settleInstall` awaits the verdict — a preResolution hook or the
+    // install kickoff below could throw and bail out before we get there.
+    verifyLockfilePromise.catch(() => {})
 }

Evidence

The PR replaced the earlier inline verification try/catch with a concurrently-started promise
(verifyLockfilePromise = verifyLockfileResolutions(...) plus a no-op catch), but the pacquet error
comment still references the old try/catch, which no longer exists in the updated flow.

installing/deps-installer/src/install/index.ts[395-412]
installing/deps-installer/src/install/index.ts[1051-1054]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`tryFrozenInstall` has a comment that says it uses the same reasoning as a `verifyLockfileResolutions` catch block “above”, but that catch block was removed when lockfile verification was changed to run concurrently (promise kick-off + later reconciliation). The comment is now stale and misleading.
### Issue Context
`detachReporter()` is still important for the pacquet failure path, but the justification should reference the current reconciliation/cleanup approach (e.g. `settleInstall`) or be phrased generically (“user-facing failure path; detach to avoid listener leaks”).
### Fix Focus Areas
- installing/deps-installer/src/install/index.ts[1047-1054]
- installing/deps-installer/src/install/index.ts[395-412]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

A new comment in Install::run_inner claims the resolution-verifier list can be empty when there is
“no active resolution policy”, but build_resolution_verifiers documents that it always includes the
npm verifier (tarball-URL binding), making the list non-empty whenever verification is enabled. This
mismatch can mislead maintainers about when verification gates are active.

Code

pacquet/crates/package-manager/src/install.rs[R681-706]

+        // Resolution verifiers re-apply `minimumReleaseAge` /
+        // `trustPolicy='no-downgrade'` (plus the tarball-URL anti-tamper
+        // check) to every entry in the loaded `pnpm-lock.yaml`. They are
+        // built here — cheap, no I/O — but the verification fan-out itself
+        // is dispatched per path below: on the frozen materialization path
+        // it runs concurrently with the fetch (see [`InstallFrozenLockfile`])
+        // so the per-entry registry round trips overlap the download;
+        // every other path (fresh resolve, the lockfile-only / up-to-date
+        // short-circuits) verifies eagerly via [`verify_lockfile_eagerly`]
+        // before it proceeds. `trust_lockfile` (the OR of yaml's
+        // `trustLockfile` and the `--trust-lockfile` CLI flag, resolved in
+        // [`crate::cli_args::install::InstallArgs::run`]; the opt-out for
+        // environments that treat the on-disk lockfile as already-trusted,
+        // see [#11860]) or no active resolution policy leaves the list
+        // empty, making every gate a no-op — fresh local resolution is
+        // already filtered by the resolver's own per-version gate
+        // (`minimumReleaseAge` via `ResolveResult::policy_violation`,
+        // `trustPolicy='no-downgrade'` via the npm resolver's
+        // `fail_if_trust_downgraded_for_pick`). The list is built whenever
+        // a policy could apply, independent of whether a lockfile is loaded, so the
+        // fresh-resolve path can record the freshly written lockfile as
+        // already-verified (see `record_lockfile_verified` below). Mirrors
+        // pnpm's wiring at
+        // <https://github.com/pnpm/pnpm/blob/2a9bd897bf/installing/deps-installer/src/install/index.ts#L355-L383>
+        // and its concurrent verification + build gate.
+        //

Evidence

The install path comment asserts emptiness under “no active resolution policy”, but the verifier
builder’s own documentation states it always includes the npm verifier, implying the list is
non-empty whenever built.

pacquet/crates/package-manager/src/install.rs[681-720]
pacquet/crates/package-manager/src/build_resolution_verifiers.rs[61-64]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`Install::run_inner`’s new comment says the verifier list can be empty when there is “no active resolution policy”. However, `build_resolution_verifiers` is documented to always include the npm verifier (tarball-URL binding), so in practice the list is non-empty whenever verification is enabled (i.e. when `trust_lockfile` is false).
### Issue Context
This is a comment/documentation inconsistency: the code behavior is correct, but the comment describes a different runtime shape, which can cause incorrect future edits.
### Fix Focus Areas
- pacquet/crates/package-manager/src/install.rs[681-706]
- pacquet/crates/package-manager/src/build_resolution_verifiers.rs[61-64]
### Suggested fix
Update the comment to reflect actual behavior:
- Clarify that the list is empty only when `trust_lockfile` is enabled (or other explicit opt-out), and that the npm verifier is always present otherwise (even when policy knobs like `minimumReleaseAge` / `trustPolicy` are unset).
- If you intended a truly-empty list when policies are off, that would require changing `build_resolution_verifiers` and would weaken the always-on tarball URL anti-tamper binding; avoid that unless explicitly desired.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

• Run lockfile verification concurrently with fetch/link on frozen installs to reduce wall time.
• Gate dependency lifecycle scripts on verification verdict across headless and full install paths.
• Add pnpr /v1/verify-lockfile flow for pacquet and tests ensuring scripts never run unverified.

The following are alternative approaches to this PR:

Recommendation: Keep the PR’s approach: overlapping verification with fetch/link provides the performance win while maintaining the critical security guarantee via an explicit pre-script gate. The chosen reconciliation strategy (await verification first for error precedence + fail-fast) is appropriate, and the added tests specifically cover the highest-risk regression (scripts running before verification).

index.ts Run lockfile verification concurrently and gate scripts via verifyLockfile +60/-17

Run lockfile verification concurrently and gate scripts via verifyLockfile

• Starts lockfile verification as an un-awaited promise and reconciles it with the install via 'settleInstall', ensuring verification failures fail fast and take precedence. Threads a 'verifyLockfile' callback into build entry points and awaits it immediately before 'buildModules' so dependency scripts never run on an unverified lockfile.

installing/deps-installer/src/install/index.ts

---

index.ts Add verifyLockfile callback to headless install options +9/-0

Add verifyLockfile callback to headless install options

• Extends 'HeadlessOptions' with an optional 'verifyLockfile' hook and awaits it right before 'buildModules', enabling overlap of verification with fetch/link while preserving the no-scripts-before-verdict guarantee.

installing/deps-restorer/src/index.ts

---

install.rs Wire pnpr lockfile verification override into frozen installs +80/-2

Wire pnpr lockfile verification override into frozen installs

• For frozen, non-lockfile-only pnpr installs, prefetches tarballs from the local lockfile and concurrently requests a verification verdict using the pnpr client. Passes a verification future into the package-manager via 'run_with_lockfile_verification', mapping failures into a consistent frozen-lockfile error variant.

pacquet/crates/cli/src/cli_args/install.rs

---

install.rs Dispatch verification per install path and normalize verification errors +144/-28

Dispatch verification per install path and normalize verification errors

• Refactors 'Install::run' into an inner runner supporting an optional verification override, verifies eagerly on paths without fetch to overlap, and passes verifier context into the frozen materialization path. Ensures verification failures surface as the same top-level 'InstallError::LockfileVerification' variant, including when produced by the frozen path.

pacquet/crates/package-manager/src/install.rs

---

install_frozen_lockfile.rs Run lockfile verification concurrently with CreateVirtualStore via try_join! +92/-28

Run lockfile verification concurrently with CreateVirtualStore via try_join!

• Adds verifier inputs and an optional verification override to the frozen install subroutine. Executes verification concurrently with the fetch/materialization phase using 'tokio::try_join!' to fail fast and ensures the verdict is reached before linking/build steps.

pacquet/crates/package-manager/src/install_frozen_lockfile.rs

---

tarball_prefetch.rs Add prefetch_lockfile to queue tarball downloads from lockfile entries +29/-0

Add prefetch_lockfile to queue tarball downloads from lockfile entries

• Introduces 'prefetch_lockfile' to enqueue registry tarball downloads for all registry-resolved lockfile packages and adds URL construction helper logic.

pacquet/crates/package-manager/src/tarball_prefetch.rs

---

lib.rs Add VerifyLockfileOptions and /v1/verify-lockfile client support +116/-0

Add VerifyLockfileOptions and /v1/verify-lockfile client support

• Adds a new request type derived from resolve options and implements a streaming NDJSON client for '/v1/verify-lockfile' that returns success on a terminal 'done' frame and maps 'violations' into a structured verification error.

pacquet/crates/pnpr-client/src/lib.rs

---

resolver.rs Implement POST /v1/verify-lockfile endpoint returning terminal verdict frame +45/-0

Implement POST /v1/verify-lockfile endpoint returning terminal verdict frame

• Adds a resolver handler that validates input, optionally short-circuits when 'trust_lockfile' is set, and otherwise verifies the provided lockfile under policy settings without resolving, returning a single NDJSON verdict frame.

pnpr/crates/pnpr/src/resolver.rs

---

server.rs Route /v1/verify-lockfile to resolver handler +8/-1

Route /v1/verify-lockfile to resolver handler

• Registers the new '/v1/verify-lockfile' route and wires it into the resolver runtime initialization path.

pnpr/crates/pnpr/src/server.rs

---

trustLockfile.ts Test that postinstall scripts do not run when verification fails +28/-1

Test that postinstall scripts do not run when verification fails

• Adds an integration test that installs a package with a postinstall script under a rejecting verifier and asserts the install fails and the postinstall-generated file is absent.

installing/deps-installer/test/install/trustLockfile.ts

---

pnpr_install.rs Add CLI test asserting frozen pnpr install verifies lockfile without resolving +47/-0

Add CLI test asserting frozen pnpr install verifies lockfile without resolving

• Adds a test that performs an initial install to create a lockfile, removes node_modules, then performs a frozen install against a mocked '/v1/verify-lockfile' endpoint and asserts verification is called and node_modules links are created.

pacquet/crates/cli/tests/pnpr_install.rs

---

integration.rs Add integration tests for verify-lockfile endpoint success and rejection +50/-1

Add integration tests for verify-lockfile endpoint success and rejection

• Adds tests verifying that a clean lockfile is accepted and that a policy violation (huge minimumReleaseAge) is rejected with a verification error containing the expected breakdown.

pacquet/crates/pnpr-client/tests/integration.rs

---

parallel-lockfile-verification.md Add changeset describing concurrent lockfile verification speedup +7/-0

Add changeset describing concurrent lockfile verification speedup

• Introduces a changeset documenting the new behavior: verification runs concurrently with fetching/linking while still gating lifecycle scripts on a successful verdict.

.changeset/parallel-lockfile-verification.md

---