@pnpm/installing.deps-installer 1101.1.1 → 1101.2.0

package/lib/install/extendInstallOptions.d.ts

@@ -5,7 +5,7 @@ import type { ProjectOptions } from '@pnpm/installing.context';
 import type { HoistingLimits } from '@pnpm/installing.deps-restorer';
 import type { IncludedDependencies } from '@pnpm/installing.modules-yaml';
 import type { LockfileObject } from '@pnpm/lockfile.fs';
-import type { WorkspacePackages } from '@pnpm/resolving.resolver-base';
+import type { ResolutionPolicyViolation, ResolutionVerifier, WorkspacePackages } from '@pnpm/resolving.resolver-base';
 import type { StoreController } from '@pnpm/store.controller-types';
 import type { AllowedDeprecatedVersions, PackageExtension, PackageVulnerabilityAudit, PeerDependencyRules, ReadPackageHook, Registries, RegistryConfig, SupportedArchitectures, TrustPolicy } from '@pnpm/types';
 import type { ReporterFunction } from '../types.js';
@@ -148,6 +148,39 @@ export interface StrictInstallOptions {
     ci?: boolean;
     minimumReleaseAge?: number;
     minimumReleaseAgeExclude?: string[];
+    /**
+     * Resolver-agnostic post-tree gate, invoked between
+     * `resolveDependencyTree` and `resolvePeers` inside
+     * `resolveDependencies`. Receives the violations the verifier
+     * fan-out collected from the freshly-resolved tree. Throwing here
+     * unwinds the install before peer-dep resolution runs — nothing on
+     * disk has changed, and the (potentially expensive) peer pass is
+     * skipped on abort.
+     *
+     * Intentionally policy-neutral. Each verifier owns its violation
+     * codes (`MINIMUM_RELEASE_AGE_VIOLATION`, `TRUST_DOWNGRADE`, …); the
+     * install command filters by code to decide what to do. Future
+     * resolvers can plug verifiers in without touching this signature.
+     */
+    handleResolutionPolicyViolations?: (violations: readonly ResolutionPolicyViolation[]) => Promise<void>;
+    /**
+     * Resolver-side verifiers that re-check each lockfile-pinned resolution
+     * against policies configured upstream (today: at most one,
+     * `npm.minimumReleaseAge` in strict mode). Constructed by `createClient`
+     * and surfaced via the `createStoreController` return; mutateModules
+     * fans out across the list once, right after the lockfile is loaded
+     * from disk. Empty when no policy is active.
+     */
+    resolutionVerifiers: ResolutionVerifier[];
+    /**
+     * pnpm's on-disk cache directory. When set together with non-empty
+     * `resolutionVerifiers`, the lockfile verification result is memoized
+     * in `<cacheDir>/lockfile-verified.jsonl` so repeat installs against an
+     * unchanged lockfile skip the per-package registry round trip. The
+     * record is policy-neutral; each active resolver-side verifier writes
+     * its own slot under `verifiers[<key>]`.
+     */
+    cacheDir?: string;
     trustPolicy?: TrustPolicy;
     trustPolicyExclude?: string[];
     trustPolicyIgnoreAfter?: number;

package/lib/install/extendInstallOptions.js

@@ -102,6 +102,7 @@ const defaults = (opts) => {
         peersSuffixMaxLength: 1000,
         blockExoticSubdeps: false,
         omitSummaryLog: false,
+        resolutionVerifiers: [],
     };
 };
 export function extendOptions(opts) {

package/lib/install/index.d.ts

@@ -2,7 +2,7 @@ import type { Catalogs } from '@pnpm/catalogs.types';
 import { PnpmError } from '@pnpm/error';
 import { type PinnedVersion, type UpdateMatchingFunction, type WantedDependency } from '@pnpm/installing.deps-resolver';
 import { type InstallationResultStats } from '@pnpm/installing.deps-restorer';
-import type { PreferredVersions } from '@pnpm/resolving.resolver-base';
+import type { PreferredVersions, ResolutionPolicyViolation } from '@pnpm/resolving.resolver-base';
 import type { DependenciesField, DepPath, IgnoredBuilds, PeerDependencyIssues, ProjectId, ProjectManifest, ProjectRootDir, ReadPackageHook } from '@pnpm/types';
 import { type InstallOptions } from './extendInstallOptions.js';
 interface InstallMutationOptions {
@@ -45,6 +45,8 @@ export interface InstallResult {
     updatedCatalogs: Catalogs | undefined;
     updatedManifest: ProjectManifest;
     ignoredBuilds: IgnoredBuilds | undefined;
+    /** Forwarded from {@link MutateModulesResult.resolutionPolicyViolations}. */
+    resolutionPolicyViolations: ResolutionPolicyViolation[];
 }
 export declare function install(manifest: ProjectManifest, opts: Opts): Promise<InstallResult>;
 export type MutatedProject = DependenciesMutation & {
@@ -60,6 +62,8 @@ export interface MutateModulesInSingleProjectResult {
     updatedCatalogs: Catalogs | undefined;
     updatedProject: UpdatedProject;
     ignoredBuilds: IgnoredBuilds | undefined;
+    /** Forwarded from {@link MutateModulesResult.resolutionPolicyViolations}. */
+    resolutionPolicyViolations: ResolutionPolicyViolation[];
 }
 export declare function mutateModulesInSingleProject(project: MutatedProject & {
     binsDir?: string;
@@ -73,6 +77,15 @@ export interface MutateModulesResult {
     stats: InstallationResultStats;
     depsRequiringBuild?: DepPath[];
     ignoredBuilds: IgnoredBuilds | undefined;
+    /**
+     * Resolver-policy violations the post-resolution scan found in the
+     * freshly-resolved lockfile. Each violation carries a verifier code
+     * (e.g. `MINIMUM_RELEASE_AGE_VIOLATION`, `TRUST_DOWNGRADE`); the
+     * install command filters by code to decide what to do (persist to
+     * `minimumReleaseAgeExclude`, log, etc.). Empty array when no
+     * verifier reported a violation or no policy was active.
+     */
+    resolutionPolicyViolations: ResolutionPolicyViolation[];
 }
 export declare function mutateModules(projects: MutatedProject[], maybeOpts: MutateModulesOptions): Promise<MutateModulesResult>;
 export declare function addDependenciesToPackage(manifest: ProjectManifest, dependencySelectors: string[], opts: Omit<InstallOptions, 'allProjects'> & {

package/lib/install/index.js

@@ -15,7 +15,7 @@ import { getContext } from '@pnpm/installing.context';
 import { getWantedDependencies, resolveDependencies, } from '@pnpm/installing.deps-resolver';
 import { extendProjectsWithTargetDirs, headlessInstall } from '@pnpm/installing.deps-restorer';
 import { writeModulesManifest } from '@pnpm/installing.modules-yaml';
-import { cleanGitBranchLockfiles, readWantedLockfile, writeCurrentLockfile, writeLockfiles, writeWantedLockfile, } from '@pnpm/lockfile.fs';
+import { cleanGitBranchLockfiles, getWantedLockfileName, readWantedLockfile, writeCurrentLockfile, writeLockfiles, writeWantedLockfile, } from '@pnpm/lockfile.fs';
 import { getPreferredVersionsFromLockfileAndManifests } from '@pnpm/lockfile.preferred-versions';
 import { calcPatchHashes, createOverridesMapFromParsed, getOutdatedLockfileSetting, } from '@pnpm/lockfile.settings-checker';
 import { writePnpFile } from '@pnpm/lockfile.to-pnp';
@@ -38,6 +38,9 @@ import { extendOptions, } from './extendInstallOptions.js';
 import { linkPackages } from './link.js';
 import { reportPeerDependencyIssues } from './reportPeerDependencyIssues.js';
 import { validateModules } from './validateModules.js';
+import { verifyLockfileResolutions } from './verifyLockfileResolutions.js';
+import { writeLockfilesAndRecordVerified } from './writeLockfilesAndRecordVerified.js';
+import { writeWantedLockfileAndRecordVerified } from './writeWantedLockfileAndRecordVerified.js';
 class LockfileConfigMismatchError extends PnpmError {
     constructor(outdatedLockfileSettingName) {
         super('LOCKFILE_CONFIG_MISMATCH', `Cannot proceed with the frozen installation. The current "${outdatedLockfileSettingName}" configuration doesn't match the value found in the lockfile`, {
@@ -57,7 +60,7 @@ export async function install(manifest, opts) {
     if (opts.agent) {
         return installFromPnpmRegistry(manifest, rootDir, opts);
     }
-    const { updatedCatalogs, updatedProjects: projects, ignoredBuilds } = await mutateModules([
+    const { updatedCatalogs, updatedProjects: projects, ignoredBuilds, resolutionPolicyViolations } = await mutateModules([
         {
             mutation: 'install',
             pruneDirectDependencies: opts.pruneDirectDependencies,
@@ -76,7 +79,7 @@ export async function install(manifest, opts) {
                 binsDir: opts.binsDir,
             }],
     });
-    return { updatedCatalogs, updatedManifest: projects[0].manifest, ignoredBuilds };
+    return { updatedCatalogs, updatedManifest: projects[0].manifest, ignoredBuilds, resolutionPolicyViolations };
 }
 export async function mutateModulesInSingleProject(project, maybeOpts) {
     const result = await mutateModules([
@@ -98,6 +101,7 @@ export async function mutateModulesInSingleProject(project, maybeOpts) {
         updatedCatalogs: result.updatedCatalogs,
         updatedProject: result.updatedProjects[0],
         ignoredBuilds: result.ignoredBuilds,
+        resolutionPolicyViolations: result.resolutionPolicyViolations,
     };
 }
 const pickCatalogSpecifier = {
@@ -107,6 +111,11 @@ const pickCatalogSpecifier = {
 };
 export async function mutateModules(projects, maybeOpts) {
     const reporter = maybeOpts?.reporter;
+    const detachReporter = (reporter != null) && typeof reporter === 'function'
+        ? () => {
+            streamParser.removeListener('data', reporter);
+        }
+        : () => { };
     if ((reporter != null) && typeof reporter === 'function') {
         streamParser.on('data', reporter);
     }
@@ -153,6 +162,36 @@ export async function mutateModules(projects, maybeOpts) {
             ctx = await getContext(opts);
         }
     }
+    // Re-validate every entry in the lockfile against the policies the
+    // resolver chain was built with (today: minimumReleaseAge in strict mode
+    // via the npm verifier; the abstraction supports other resolvers
+    // attaching their own verifiers). The threat model is a lockfile that
+    // someone else resolved — committed to the repo, restored from a CI
+    // cache, etc. — bypassing the local resolver's policy filters; the local
+    // resolver's own filters already cover fresh resolution. We run this
+    // exactly once, right after the lockfile is loaded from disk, before any
+    // path branches.
+    const cacheActive = opts.cacheDir != null && opts.resolutionVerifiers.length > 0;
+    const wantedLockfilePath = cacheActive
+        ? path.resolve(ctx.lockfileDir, await getWantedLockfileName({
+            useGitBranchLockfile: opts.useGitBranchLockfile,
+            mergeGitBranchLockfiles: opts.mergeGitBranchLockfiles,
+        }))
+        : undefined;
+    try {
+        await verifyLockfileResolutions(ctx.wantedLockfile, opts.resolutionVerifiers, {
+            cacheDir: opts.cacheDir,
+            lockfilePath: wantedLockfilePath,
+        });
+    }
+    catch (err) {
+        // verifyLockfileResolutions is the one throw site in this function
+        // that's part of normal user-facing operation (a rejected lockfile);
+        // other throws here are unexpected. Detach the reporter listener so
+        // long-lived processes don't leak it on every rejected install.
+        detachReporter();
+        throw err;
+    }
     if (opts.hooks.preResolution) {
         for (const preResolution of opts.hooks.preResolution) {
             // eslint-disable-next-line no-await-in-loop
@@ -227,15 +266,14 @@ export async function mutateModules(projects, maybeOpts) {
     ignoredScriptsLogger.debug({
         packageNames: ignoredBuilds ? dedupePackageNamesFromIgnoredBuilds(ignoredBuilds) : [],
     });
-    if ((reporter != null) && typeof reporter === 'function') {
-        streamParser.removeListener('data', reporter);
-    }
+    detachReporter();
     return {
         updatedCatalogs: result.updatedCatalogs,
         updatedProjects: result.updatedProjects,
         stats: result.stats ?? { added: 0, removed: 0, linkedToRoot: 0 },
         depsRequiringBuild: result.depsRequiringBuild,
         ignoredBuilds,
+        resolutionPolicyViolations: result.resolutionPolicyViolations ?? [],
     };
     async function _install() {
         const scriptsOpts = {
@@ -472,8 +510,9 @@ export async function mutateModules(projects, maybeOpts) {
                 defaultCatalog: opts.catalogs?.default,
             });
             if (opts.catalogMode !== 'manual') {
-                const catalogBareSpecifier = `catalog:${opts.saveCatalogName == null || opts.saveCatalogName === 'default' ? '' : opts.saveCatalogName}`;
                 for (const wantedDep of wantedDeps) {
+                    const perDepCatalogName = getPerDepCatalogName(wantedDep, opts.saveCatalogName);
+                    const catalogBareSpecifier = `catalog:${perDepCatalogName === 'default' ? '' : perDepCatalogName}`;
                     const catalog = resolveFromCatalog(opts.catalogs, { ...wantedDep, bareSpecifier: catalogBareSpecifier });
                     const catalogDepSpecifier = matchCatalogResolveResult(catalog, pickCatalogSpecifier);
                     if (!catalogDepSpecifier ||
@@ -481,7 +520,7 @@ export async function mutateModules(projects, maybeOpts) {
                         semver.validRange(wantedDep.bareSpecifier) &&
                             semver.validRange(catalogDepSpecifier) &&
                             semver.eq(wantedDep.bareSpecifier, catalogDepSpecifier)) {
-                        wantedDep.saveCatalogName = opts.saveCatalogName ?? 'default';
+                        wantedDep.saveCatalogName = perDepCatalogName;
                         continue;
                     }
                     switch (opts.catalogMode) {
@@ -522,6 +561,7 @@ export async function mutateModules(projects, maybeOpts) {
             stats: result.stats,
             depsRequiringBuild: result.depsRequiringBuild,
             ignoredBuilds: result.ignoredBuilds,
+            resolutionPolicyViolations: result.resolutionPolicyViolations,
         };
     }
     /**
@@ -791,9 +831,26 @@ function isWantedDepBareSpecifierSame(prevCatalogs, catalogsConfig, alias, prevB
     const nextCatalogEntrySpec = catalogsConfig?.[catalogName]?.[alias];
     return prevCatalogEntrySpec === nextCatalogEntrySpec;
 }
+/**
+ * Determines the catalog name for a dependency during installSome.
+ *
+ * If the dependency's previous specifier already uses a named catalog
+ * (e.g. "catalog:foo"), that catalog name takes priority over the global
+ * saveCatalogName option. This ensures that interactive updates and
+ * `--latest` upgrades preserve the per-dependency catalog group.
+ */
+function getPerDepCatalogName(wantedDep, globalSaveCatalogName) {
+    if (wantedDep.prevSpecifier) {
+        const catalogFromPrev = parseCatalogProtocol(wantedDep.prevSpecifier);
+        if (catalogFromPrev != null) {
+            return catalogFromPrev;
+        }
+    }
+    return globalSaveCatalogName ?? 'default';
+}
 export async function addDependenciesToPackage(manifest, dependencySelectors, opts) {
     const rootDir = (opts.dir ?? process.cwd());
-    const { updatedCatalogs, updatedProjects: projects, ignoredBuilds } = await mutateModules([
+    const { updatedCatalogs, updatedProjects: projects, ignoredBuilds, resolutionPolicyViolations } = await mutateModules([
         {
             allowNew: opts.allowNew,
             dependencySelectors,
@@ -819,7 +876,7 @@ export async function addDependenciesToPackage(manifest, dependencySelectors, op
             },
         ],
     });
-    return { updatedCatalogs, updatedManifest: projects[0].manifest, ignoredBuilds };
+    return { updatedCatalogs, updatedManifest: projects[0].manifest, ignoredBuilds, resolutionPolicyViolations };
 }
 const _installInContext = async (projects, ctx, opts) => {
     // The wanted lockfile is mutated during installation. To compare changes, a
@@ -892,7 +949,7 @@ const _installInContext = async (projects, ctx, opts) => {
         // ignores preferred versions from the lockfile.
         forgetResolutionsOfAllPrevWantedDeps(ctx.wantedLockfile);
     }
-    let { dependenciesGraph, dependenciesByProjectId, linkedDependenciesByProjectId, updatedCatalogs, newLockfile, outdatedDependencies, peerDependencyIssuesByProjects, wantedToBeSkippedPackageIds, waitTillAllFetchingsFinish, } = await resolveDependencies(projects, {
+    let { dependenciesGraph, dependenciesByProjectId, linkedDependenciesByProjectId, updatedCatalogs, newLockfile, outdatedDependencies, peerDependencyIssuesByProjects, wantedToBeSkippedPackageIds, waitTillAllFetchingsFinish, resolutionPolicyViolations, } = await resolveDependencies(projects, {
         allowBuild: opts.allowBuild,
         allowedDeprecatedVersions: opts.allowedDeprecatedVersions,
         allowUnusedPatches: opts.allowUnusedPatches,
@@ -946,6 +1003,7 @@ const _installInContext = async (projects, ctx, opts) => {
         trustPolicyIgnoreAfter: opts.trustPolicyIgnoreAfter,
         blockExoticSubdeps: opts.blockExoticSubdeps,
         allProjectIds: Object.values(ctx.projects).map((p) => p.id),
+        handleResolutionPolicyViolations: opts.handleResolutionPolicyViolations,
     });
     if (!opts.include.optionalDependencies || !opts.include.devDependencies || !opts.include.dependencies) {
         linkedDependenciesByProjectId = mapValues((linkedDeps) => linkedDeps.filter((linkedDep) => !(linkedDep.dev && !opts.include.devDependencies ||
@@ -1160,11 +1218,13 @@ const _installInContext = async (projects, ctx, opts) => {
         const currentLockfileDir = path.join(ctx.rootModulesDir, '.pnpm');
         await Promise.all([
             opts.useLockfile && opts.saveLockfile
-                ? writeLockfiles({
+                ? writeLockfilesAndRecordVerified({
                     currentLockfile: result.currentLockfile,
                     currentLockfileDir,
                     wantedLockfile: newLockfile,
                     wantedLockfileDir: ctx.lockfileDir,
+                    cacheDir: opts.cacheDir,
+                    resolutionVerifiers: opts.resolutionVerifiers,
                     ...lockfileOpts,
                 })
                 : writeCurrentLockfile(ctx.virtualStoreDir, result.currentLockfile),
@@ -1216,7 +1276,13 @@ const _installInContext = async (projects, ctx, opts) => {
     }
     else {
         if (opts.useLockfile && opts.saveLockfile && !isInstallationOnlyForLockfileCheck) {
-            await writeWantedLockfile(ctx.lockfileDir, newLockfile, lockfileOpts);
+            await writeWantedLockfileAndRecordVerified({
+                lockfileDir: ctx.lockfileDir,
+                lockfile: newLockfile,
+                cacheDir: opts.cacheDir,
+                resolutionVerifiers: opts.resolutionVerifiers,
+                ...lockfileOpts,
+            });
         }
         if (opts.nodeLinker !== 'hoisted') {
             // This is only needed because otherwise the reporter will hang
@@ -1264,6 +1330,7 @@ const _installInContext = async (projects, ctx, opts) => {
         stats,
         depsRequiringBuild,
         ignoredBuilds,
+        resolutionPolicyViolations,
     };
 };
 function allMutationsAreInstalls(projects) {
@@ -1627,6 +1694,14 @@ async function mutateModulesViaAgent(projects, opts) {
  * packages into node_modules.
  */
 async function installFromPnpmRegistry(manifest, rootDir, opts, allInstallProjects) {
+    // The agent path skips client-side resolution, so resolver-side policies
+    // can't be enforced locally. `minimumReleaseAge` is forwarded to the
+    // agent and enforced server-side. `trustPolicy` has no server-side
+    // counterpart yet, so refuse to run under it instead of silently
+    // letting through a lockfile the local verifier would reject.
+    if (opts.trustPolicy === 'no-downgrade') {
+        throw new PnpmError('TRUST_POLICY_INCOMPATIBLE_WITH_AGENT', 'The pnpm agent does not yet enforce `trustPolicy: no-downgrade`, so running an install through the agent under this policy would produce a lockfile that the local verifier rejects.', { hint: 'Unset `trustPolicy` for this install, or disable the agent (unset `--agent` / `agent` in pnpm-workspace.yaml) so resolution runs locally and the trust check applies.' });
+    }
     const { fetchFromPnpmRegistry } = await import('@pnpm/agent.client');
     const { StoreIndex } = await import('@pnpm/store.index');
     const { setImportConcurrency } = await import('@pnpm/worker');
@@ -1677,7 +1752,14 @@ async function installFromPnpmRegistry(manifest, rootDir, opts, allInstallProjec
         finally {
             storeIndex.close();
         }
-        await writeWantedLockfile(lockfileDir, lockfile);
+        await writeWantedLockfileAndRecordVerified({
+            lockfileDir,
+            lockfile,
+            cacheDir: opts.cacheDir,
+            resolutionVerifiers: opts.resolutionVerifiers,
+            useGitBranchLockfile: opts.useGitBranchLockfile,
+            mergeGitBranchLockfiles: opts.mergeGitBranchLockfiles,
+        });
         logger.info({
             message: `Resolved ${agentStats.totalPackages} packages: ${agentStats.alreadyInStore} cached, ${agentStats.filesToDownload} files to download`,
             prefix: rootDir,
@@ -1757,6 +1839,12 @@ async function installFromPnpmRegistry(manifest, rootDir, opts, allInstallProjec
             ignoredBuilds,
             stats,
             lockfile,
+            // Server-side resolution (pnpm agent) enforces `minimumReleaseAge`
+            // itself — the agent picks only mature versions and the lockfile
+            // can't contain immature entries to auto-collect. `trustPolicy` is
+            // guarded above (we refuse to enter this path when it's set), so
+            // there's nothing for the install command to react to here.
+            resolutionPolicyViolations: [],
         };
     }
     finally {

package/lib/install/link.js

@@ -1,7 +1,7 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { progressLogger, stageLogger, statsLogger, } from '@pnpm/core-loggers';
-import { calcDepState } from '@pnpm/deps.graph-hasher';
+import { calcDepState, findRuntimeNodeVersion } from '@pnpm/deps.graph-hasher';
 import { symlinkDependency } from '@pnpm/fs.symlink-dependency';
 import { linkDirectDeps } from '@pnpm/installing.linking.direct-dep-linker';
 import { hoist } from '@pnpm/installing.linking.hoist';
@@ -318,6 +318,11 @@ async function selectNewFromWantedDeps(wantedRelDepPaths, currentLockfile, depGr
 }
 const limitLinking = pLimit(16);
 async function linkAllPkgs(storeController, depNodes, opts) {
+    // Resolved `engines.runtime` Node version (when present) so the
+    // side-effects-cache key prefix tracks the script-runner Node
+    // rather than pnpm's own `process.version`. Computed once outside
+    // the per-node loop.
+    const nodeVersion = findRuntimeNodeVersion(Object.keys(opts.depGraph));
     await Promise.all(depNodes.map(async (depNode) => {
         const { files } = await depNode.fetching();
         depNode.requiresBuild = files.requiresBuild;
@@ -328,6 +333,7 @@ async function linkAllPkgs(storeController, depNodes, opts) {
                     includeDepGraphHash: !opts.ignoreScripts && depNode.requiresBuild, // true when is built
                     patchFileHash: depNode.patch?.hash,
                     supportedArchitectures: opts.supportedArchitectures,
+                    nodeVersion,
                 });
             }
         }

package/lib/install/recordLockfileVerified.d.ts

@@ -0,0 +1,22 @@
+import type { LockfileObject } from '@pnpm/lockfile.fs';
+import type { ResolutionVerifier } from '@pnpm/resolving.resolver-base';
+export interface RecordLockfileVerifiedOptions {
+    cacheDir?: string;
+    /** Absolute path of the lockfile the next install will read.
+     *  Under `useGitBranchLockfile` this is the branch-suffixed name. */
+    lockfilePath: string;
+    /** The writer's canonical return value — see {@link writeWantedLockfile}.
+     *  Passing the raw in-memory write object would record a hash the
+     *  next install can't match (YAML drops undefined fields). */
+    lockfile: LockfileObject;
+    resolutionVerifiers: readonly ResolutionVerifier[] | undefined;
+}
+/**
+ * Records the post-resolution lockfile as verified so the next install
+ * skips the registry round-trip. Skipping is safe: fresh local picks
+ * are filtered by the resolver (see
+ * `resolving/npm-resolver/src/pickPackage.ts`) and carried-over entries
+ * already passed the gate at the top of `mutateModules`, so the
+ * recorded lockfile is policy-clean by construction.
+ */
+export declare function recordLockfileVerified(opts: RecordLockfileVerifiedOptions): void;

package/lib/install/recordLockfileVerified.js

@@ -0,0 +1,24 @@
+import { hashObject } from '@pnpm/crypto.object-hasher';
+import { recordVerification } from './verifyLockfileResolutionsCache.js';
+/**
+ * Records the post-resolution lockfile as verified so the next install
+ * skips the registry round-trip. Skipping is safe: fresh local picks
+ * are filtered by the resolver (see
+ * `resolving/npm-resolver/src/pickPackage.ts`) and carried-over entries
+ * already passed the gate at the top of `mutateModules`, so the
+ * recorded lockfile is policy-clean by construction.
+ */
+export function recordLockfileVerified(opts) {
+    if (!opts.cacheDir)
+        return;
+    if (!opts.resolutionVerifiers?.length)
+        return;
+    if (!opts.lockfile.packages)
+        return;
+    recordVerification(opts.cacheDir, {
+        lockfilePath: opts.lockfilePath,
+        verifiers: opts.resolutionVerifiers,
+        hashLockfile: () => hashObject(opts.lockfile),
+    });
+}
+//# sourceMappingURL=recordLockfileVerified.js.map

package/lib/install/verifyLockfileResolutions.d.ts

@@ -0,0 +1,59 @@
+import type { LockfileObject } from '@pnpm/lockfile.fs';
+import type { ResolutionPolicyViolation, ResolutionVerifier } from '@pnpm/resolving.resolver-base';
+export type { ResolutionPolicyViolation };
+export interface VerifyLockfileResolutionsOptions {
+    concurrency?: number;
+    /**
+     * pnpm's on-disk cache directory. When set together with
+     * `lockfilePath`, verification results are memoized in
+     * `<cacheDir>/lockfile-verified.jsonl` and the gate short-circuits on
+     * a repeat run against an unchanged lockfile + same-or-stricter
+     * policy. Omit to disable the cache entirely (every call rehashes
+     * the lockfile and re-verifies).
+     */
+    cacheDir?: string;
+    /** Absolute path of the lockfile being verified. Used by the cache's stat shortcut. */
+    lockfilePath?: string;
+}
+/**
+ * Policy-neutral pass that asks every resolver-supplied
+ * {@link ResolutionVerifier} to check every entry in a lockfile loaded
+ * from disk. Iteration runs before resolution decisions are touched and
+ * before any tarball is fetched, so a lockfile whose entries were
+ * resolved elsewhere (committed to the repo, restored from a cache,
+ * etc.) under a weaker or absent policy cannot reach the filesystem.
+ * Fresh local resolution is covered by the resolver's own per-version
+ * filter.
+ *
+ * Each verifier handles its own protocol short-circuit inside `verify`
+ * (returning `{ ok: true }` for resolutions outside its scope), so the
+ * fan-out is policy-neutral and dispatch-free at this layer.
+ *
+ * Designed for fail-closed semantics at the verifier level: a verifier
+ * that can't confirm a resolution is expected to return `{ ok: false }`
+ * rather than passing silently — otherwise a registry hiccup or an
+ * unpublished version would re-open the bypass.
+ *
+ * No-op when `verifiers` is empty.
+ *
+ * When `options.cacheDir` and `options.lockfilePath` are both
+ * provided, an unchanged lockfile that has already been verified
+ * under the same (or stricter) policy short-circuits the registry
+ * round-trip entirely — see {@link tryLockfileVerificationCache} for
+ * the lookup logic.
+ */
+export declare function verifyLockfileResolutions(lockfile: LockfileObject, verifiers: ResolutionVerifier[], options?: VerifyLockfileResolutionsOptions): Promise<void>;
+/**
+ * Collect-mode sibling of {@link verifyLockfileResolutions}: runs the
+ * same fan-out over every verifier and every lockfile entry, but
+ * returns the violations as data instead of throwing on the first batch.
+ * No cache lookup or write — the throw-mode `verifyLockfileResolutions`
+ * is what populates / honors the cache; this is for callers that need
+ * to inspect violations (auto-collect into `minimumReleaseAgeExclude`,
+ * the strict-mode interactive prompt, future resolver-specific
+ * policies).
+ *
+ * Returns an empty array when `verifiers` is empty or the lockfile has
+ * no packages, so callers don't need a separate emptiness check.
+ */
+export declare function collectResolutionPolicyViolations(lockfile: LockfileObject, verifiers: ResolutionVerifier[], options?: Pick<VerifyLockfileResolutionsOptions, 'concurrency'>): Promise<ResolutionPolicyViolation[]>;