RFC 0001: Consume pnpm lockfiles as hermetic build inputs

[Windsor Nguyễn (windsornguyen)]

RFC: Consume pnpm lockfiles as hermetic build inputs

Status: Proposed

Summary

BSMR should integrate with pnpm rather than replace it.

pnpm should remain responsible for npm ecosystem semantics: interpreting
manifests, resolving versions and peer dependencies, applying overrides and
catalogs, and writing pnpm-lock.yaml. BSMR should consume the committed
lockfile as an immutable dependency graph, fetch and verify the selected
artifacts, materialize a pnpm-compatible dependency layout, and execute approved
package build steps as normal BSMR actions.

This design is successful only if it improves the outcomes developers actually
care about:

• Correctness: the resolved graph is preserved exactly, cache hits are
  sound, target-platform dependencies are selected correctly, and unsupported
  cases fail instead of silently changing semantics.
• Speed: packages are fetched lazily and concurrently, immutable package
  contents are shared through the CAS, and dependency build outputs can be
  reused locally or remotely.
• Security: every external artifact is authenticated by digest, build
  actions run without network access or ambient host state, and lifecycle
  scripts execute only under explicit project policy.
• Ease of use: developers continue using ordinary package.json,
  pnpm-workspace.yaml, and pnpm-lock.yaml files. BSMR must not require a
  second dependency manifest or a BSMR-specific version resolver.

The intended boundary is similar to BSMR's existing Conan integration and
Aspect's rules_js: the ecosystem package manager owns dependency resolution;
the build system owns the frozen build graph and its execution.

Decision

The proposed architecture has three explicit phases:

Phase	May use the network?	Contract
Lock update	Yes	An explicit, developer-requested pnpm resolution operation
Artifact fetch	Yes	Digest-verified acquisition into BSMR's CAS
Frozen build	No	Hermetic execution from declared source, toolchain, and CAS inputs

We should describe this publicly as hermetic frozen builds, not "hermetic
dependency resolution." Updating a lockfile necessarily consults registry state.
Once the lockfile is committed, neither dependency resolution nor public network
access belongs in the build.

User experience

The normal workflow should remain familiar:

1. A developer edits package.json or uses pnpm to add or update a dependency.
2. The project's exact, verified pnpm toolchain updates pnpm-lock.yaml.
3. The developer commits the manifests and lockfile together.
4. BSMR validates that the manifests and lockfile agree.
5. BSMR imports only the dependency closure required by the requested targets.
6. Missing artifacts are fetched by digest into the CAS.
7. Frozen build actions run without public network access.

A stale or unsupported lockfile must produce one actionable error explaining
which file or package is invalid and which explicit command updates it. BSMR
must never repair or rewrite the lockfile during an ordinary build.

Requirements

Each requirement below is intended to become an independently reviewable
implementation issue. The "not desired" sections are part of the contract, not
optional implementation advice.

1. Pin pnpm as a verified project toolchain

Desired

• Resolve an exact pnpm version from the project's standard package-manager
  declaration.
• Verify the pnpm distribution by integrity digest before execution.
• Include the exact pnpm and Node toolchains in any action that invokes pnpm.
• Support an explicit project migration from one pnpm version or lockfile schema
  to another.

Not desired

• Executing a floating latest, latest-11, or other registry tag.
• Selecting whichever pnpm happens to appear first on PATH.
• Silently overriding a repository's declared pnpm version.
• Falling back to npm, Yarn, Bun, Pacquet, or another pnpm version when the
  declared toolchain is unavailable.

Acceptance

• A clean machine obtains and verifies the declared toolchain without a global
  pnpm installation.
• A missing or mismatched toolchain fails with the expected and observed
  version and a direct remediation.
• Changing only the pnpm or Node toolchain changes every affected action key.

2. Separate resolution, fetching, and frozen builds

Desired

• Treat lockfile creation or update as an explicit operation outside the frozen
  build.
• Permit artifact fetching only in a distinct acquisition phase.
• Guarantee that the frozen build consumes the committed lockfile without
  changing it.
• Support a fully offline replay once all referenced artifacts are present in
  the CAS.

Not desired

• Running pnpm install in update mode as an implicit build step.
• Re-resolving version ranges because an artifact is absent.
• Allowing lifecycle scripts or compilers to download undeclared inputs.
• Claiming that a networked lock update is itself hermetic.

Acceptance

• A frozen build leaves every manifest and lockfile byte-for-byte unchanged.
• The same build succeeds with public network access disabled after its fetch
  phase has completed.
• Removing a required CAS object produces a missing-artifact error rather than
  a different resolution.

3. Validate the pnpm lockfile fail-closed

Desired

• Parse only explicitly supported pnpm lockfile schema versions.
• Verify that every workspace importer agrees with its corresponding manifest.
• Require immutable identities and integrity digests for external artifacts.
• Include patch contents and all resolution-affecting configuration as declared
  inputs.
• Name the exact package and field when validation fails.

Not desired

• Best-effort parsing of unknown lockfile schemas.
• Ignoring unsupported resolution fields.
• Accepting integrity-free registry or HTTP tarballs.
• Treating a URL, tag, branch, or unpinned Git reference as an immutable
  identity.
• Continuing with a partially imported graph.

Acceptance

• Fixtures cover valid and invalid schema versions, stale importers, missing
  integrity, invalid integrity, patches, aliases, overrides, catalogs, Git
  sources, HTTP tarballs, and workspace references.
• Every invalid fixture fails before any package code executes.
• The validator can report all relevant manifest/lockfile mismatches in one
  invocation without weakening fail-closed behavior.

4. Import a canonical, lossless Node dependency graph

Desired

• Represent each resolved package snapshot as a first-class graph node.
• Preserve version, source, integrity, patch identity, peer-dependency context,
  optionality, target constraints, and workspace relationships.
• Keep distinct peer-dependency variants distinct even when their package name
  and version match.
• Make the imported graph queryable and suitable for version-set validation,
  provenance, policy checks, and affected-target analysis.

Not desired

• Flattening the graph to package name and semantic version.
• Re-running semantic-version or peer-dependency resolution inside BSMR.
• Inferring omitted lockfile semantics from the current host machine.
• Treating all packages in a large workspace lockfile as dependencies of every
  target.

Acceptance

• Differential fixtures produce the same package identities and dependency
  edges as the pinned pnpm version.
• A graph query explains why a package is present, which importer selected it,
  and which peer context distinguishes it.
• Reordering semantically unordered lockfile data does not change graph
  identity; changing a semantic input does.

5. Fetch immutable package artifacts into the CAS

Desired

• Fetch every unique external package artifact once by immutable identity.
• Verify bytes against the lockfile digest before admitting them to the CAS.
• Extract package trees deterministically and address the resulting tree by
  digest.
• Perform bounded concurrent downloads with observable progress.
• Keep registry credentials outside source files, logs, provenance payloads,
  and cache keys while still binding the requested registry and artifact
  identity into the graph.

Not desired

• Caching an opaque monorepo-wide node_modules archive as the primitive.
• Trusting a registry response without verifying its digest.
• Retrying through an alternate registry or source with different semantics.
• Allowing mutable registry metadata to change a frozen graph.
• Logging authentication material.

Acceptance

• Concurrent requests for the same digest converge on one verified CAS object.
• A corrupted or substituted response is rejected before extraction.
• Warm and remote-cache builds reuse package trees without contacting the
  registry.
• Fetch metrics distinguish downloaded, locally reused, and remotely reused
  bytes and packages.

6. Select the target dependency closure

Desired

• Materialize only packages required by requested BSMR targets.
• Evaluate os, cpu, libc, engine, and optional-dependency constraints
  against the declared target and execution platforms.
• Make platform selection part of graph and action identity.
• Share identical package artifacts across target closures.

Not desired

• Selecting optional packages from the host that launched BSMR.
• Downloading every package in a monorepo lockfile for every build.
• Treating a skipped optional dependency as an unreported fallback.
• Reusing native package outputs across incompatible platforms or toolchains.

Acceptance

• Linux, macOS, Windows, architecture, libc, and optional-dependency fixtures
  select the same closure as the pinned pnpm contract.
• Cross-compilation tests prove that target selection is independent of the
  client host.
• Package closure and cache explanations show the platform predicate that
  included or excluded each conditional package.

7. Materialize a deterministic pnpm-compatible layout

Desired

• Begin with pnpm's strict, isolated, non-hoisted dependency layout.
• Preserve Node.js resolution behavior, workspace links, peer variants, package
  aliases, scoped packages, and executable shims.
• Build the layout from immutable CAS package trees and deterministic links.
• Make dependency contents read-only to ordinary build actions.
• Give each action only the dependency closure it declares.

Not desired

• Implementing a second version resolver in the linker.
• Supporting phantom dependencies through compatibility hoisting in the first
  release.
• Sharing one mutable node_modules/.pnpm directory among concurrent actions.
• Depending on the user's global pnpm store.
• Copying an entire dependency tree when links or tree composition provide the
  same semantics.

Acceptance

• Differential tests compare module resolution, real paths, .bin behavior,
  workspace links, and peer variants against pinned pnpm with hoisting disabled.
• Undeclared transitive imports fail consistently.
• Concurrent materializations cannot mutate or invalidate one another.
• Materialization is deterministic across clean output directories.

8. Model approved lifecycle hooks as build actions

Desired

• Read lifecycle trust policy from standard pnpm project configuration where
  possible.
• Execute only explicitly approved dependency hooks.
• Preserve the package's required hook order within one package build action.
• Declare the package tree, dependency closure, Node toolchain, native
  toolchains, environment, and target platform as inputs.
• Capture the post-hook package tree as a content-addressed output reusable
  locally and remotely.
• Disable public network access and provide a precise error for attempted
  undeclared downloads.

Not desired

• Running arbitrary preinstall, install, or postinstall scripts merely
  because a package contains them.
• Permanently using --ignore-scripts and pretending packages requiring builds
  are complete.
• Executing hooks in the developer's home directory or ambient shell
  environment.
• Silently rerunning a hook outside the sandbox when its sandboxed execution
  fails.
• Sharing hook outputs across incompatible platforms, toolchains, or
  environments.

Acceptance

• Fixtures cover pure JavaScript hooks, native addons, generated binaries,
  denied hooks, network attempts, undeclared writes, failures, and
  platform-specific outputs.
• An approved deterministic hook receives remote-cache hits on a second clean
  machine.
• An unapproved hook fails before execution and names the package, script, and
  policy entry required for review.

9. Expose npm packages as first-class BSMR dependencies

Desired

• Generate or expose stable BSMR targets/providers for direct npm dependencies.
• Keep transitive packages private unless a project declares them directly.
• Let JavaScript and TypeScript rules request npm packages without manually
  duplicating their versions or transitive edges in BUCK files.
• Schedule workspace builds according to the BSMR graph after dependency
  materialization.

Not desired

• One manually maintained BUCK target per transitive npm package.
• One concurrent pnpm install process per workspace package.
• Making every lockfile package visible to every build target.
• Requiring application source to replace ordinary Node import specifiers.

Acceptance

• A small workspace can add a direct dependency through its ordinary manifest
  and use it from a BSMR target without copying version data.
• Removing a direct declaration removes visibility even if another package
  still has the dependency transitively.
• Independent workspace build actions execute concurrently while respecting
  declared dependency order.

10. Make cache identity complete and explainable

Desired

• Include source tree, package snapshot, patches, lifecycle policy, toolchains,
  target and execution platforms, declared environment, materializer version,
  and relevant BSMR configuration in action identity.
• Store package fetch, extraction, lifecycle build, materialization, and
  workspace build results at the narrowest useful reusable boundary.
• Explain cache hits and misses in terms developers can act on.
• Treat a false cache hit as a correctness defect.

Not desired

• Keying only on pnpm-lock.yaml.
• Reusing native or lifecycle outputs solely because package name and version
  match.
• Hashing secrets into cache keys.
• Hiding cache invalidation behind an opaque "dependencies changed" message.
• Trading cache correctness for headline benchmark numbers.

Acceptance

• Mutation tests prove that every semantic input invalidates the affected
  actions.
• Non-semantic changes do not invalidate package artifacts.
• Cache explanations identify the first changed input or policy dimension.
• Local and remote cache results are behaviorally identical.

11. Provide provenance, policy, and diagnostics from the same graph

Desired

• Record the source URL, integrity, patch identity, importer, peer context,
  platform decision, lifecycle policy, toolchains, and producing action for each
  package artifact.
• Support SBOM, license, registry, vulnerability, and version-set policy checks
  without re-scanning an opaque node_modules tree.
• Provide human-readable "why is this package here?" and "why was this package
  rebuilt?" explanations.
• Keep user-facing errors safe while retaining detailed operator diagnostics.

Not desired

• A separate security graph that can disagree with the graph BSMR executes.
• Provenance that merely records package names and versions.
• Exposing registry credentials or private infrastructure details.
• Allowing a policy failure to degrade into a warning during protected builds.

Acceptance

• Provenance for a representative package traces from workspace declaration to
  lockfile snapshot, fetched bytes, lifecycle output, and consuming target.
• Policy checks operate before package code executes.
• SBOM and query output distinguish peer variants and target-specific optional
  packages.

12. Prove compatibility and performance before defaulting to native materialization

Desired

• Build a differential conformance suite against the exact supported pnpm
  version.
• Cover registry packages, workspaces, peers, optional dependencies, aliases,
  overrides, catalogs, patches, executable shims, lifecycle hooks, native
  addons, Git and HTTP sources, and all supported platforms.
• Benchmark cold fetch, warm materialization, no-op build, offline rebuild, and
  remote-cache restore on representative monorepos.
• Publish methodology and correctness differences alongside timing results.
• Roll out behind an explicit opt-in until compatibility gates pass.

Not desired

• Declaring parity because a smoke test exits successfully.
• Comparing only wall-clock time while ignoring installed graph differences.
• Permanently maintaining two silent implementations with automatic fallback.
• Making native materialization the default before unsupported cases fail
  clearly and documented migrations exist.

Acceptance

• Every supported fixture matches pnpm's selected package identities, module
  resolution, executable links, and lifecycle outputs.
• Known unsupported cases have deterministic pre-execution errors.
• Performance reports include machine, platform, versions, cache state,
  dependency closure, and correctness results.
• Cutover removes the old production path; it does not leave a hidden fallback.

Delivery milestones

Milestone 0: establish the pinned adapter baseline

Invoke one exact, verified pnpm per sandbox with a frozen lockfile. Capture
correctness, closure, and performance baselines. Parallelize BSMR workspace build
actions above pnpm rather than spawning one installer per package.

Exit criterion: a documented, tested baseline with no floating toolchain or
mutable lock behavior.

Milestone 1: import and validate the lockfile

Add a read-only pnpm lockfile importer and canonical graph. Use it for queries,
policy, provenance, target closure analysis, and mismatch diagnostics while
pnpm still performs materialization.

Exit criterion: differential graph tests pass for the initial supported schema
and the importer changes no build behavior.

Milestone 2: own fetching and CAS storage

Fetch verified package artifacts as individual CAS objects. Continue using the
pinned pnpm-compatible path for final materialization while validating that the
fetched closure is complete.

Exit criterion: a populated CAS supports offline frozen installation and every
artifact has verified provenance.

Milestone 3: materialize packages without pnpm

Implement strict, non-hoisted linking for packages that do not require lifecycle
hooks. Compare results continuously with pinned pnpm.

Exit criterion: supported hook-free fixtures and representative repositories
pass module-resolution and build tests without invoking pnpm during the frozen
build.

Milestone 4: actionize lifecycle hooks

Build explicitly approved dependency packages as sandboxed, cacheable,
platform-aware actions.

Exit criterion: supported native and generated-package fixtures reproduce across
clean machines and remote execution without public network access.

Milestone 5: cut over

Make BSMR-native lock consumption the only frozen-build path for the supported
surface. Keep pnpm solely for explicit lockfile resolution and updates.

Exit criterion: compatibility, security, performance, documentation, and
migration gates pass; unsupported behavior fails before execution; no automatic
fallback remains.

Initial scope

The first production-quality release should support the pnpm schema and feature
surface required by a pinned set of representative BSMR workspaces. At minimum,
that surface should include:

• Registry packages with integrity hashes
• Workspace importers and workspace: references
• Peer-dependency variants
• Optional and platform-specific dependencies
• Aliases and executable shims
• Overrides, catalogs, and patched dependencies represented by the lockfile
• Explicitly approved lifecycle hooks
• Immutable Git or HTTP artifacts with verifiable identities

Support must be defined by conformance fixtures, not by accepting arbitrary
syntax optimistically.

Non-goals

• Implement npm semantic-version or peer-dependency resolution in BSMR.
• Replace pnpm's manifest, workspace, or lockfile formats.
• Build a general-purpose package manager.
• Support npm, Yarn, Bun, and every historical pnpm lockfile in the first
  release.
• Support compatibility hoisting or undeclared phantom dependencies initially.
• Permit lifecycle scripts to access the public network during frozen builds.
• Optimize installation by running many competing pnpm install processes.
• Promise byte-for-byte reproducible outputs from tools that embed timestamps,
  randomness, absolute paths, or undeclared host information. Hermeticity is
  necessary but not sufficient for reproducibility.

Alternatives considered

Shell out to pnpm forever

This is the correct baseline and may remain sufficient for small repositories.
It does not expose package-level graph, provenance, policy, or caching boundaries
to BSMR, and it requires treating installation as one comparatively opaque
action.

Reimplement pnpm resolution

This adds a large compatibility surface without improving the initial developer
workflow. BSMR would own semver selection, peer resolution, registries,
overrides, catalogs, patches, workspace semantics, and years of ecosystem edge
cases. That work should occur only if a measured product requirement cannot be
met through the lockfile contract.

Depend on Pacquet as the primary package manager

A Rust implementation may eventually reduce integration cost, but language
choice does not establish compatibility, hermeticity, or performance. Pacquet
can be evaluated independently without making BSMR's architecture depend on its
release cadence or parity status.

Adopt rules_js directly

rules_js is the strongest public precedent for this design, but it is built
for Bazel's repository and rule APIs. BSMR should adopt the proven boundary and
conformance lessons while implementing the smallest native integration that
fits BSMR's graph, CAS, platforms, and execution model.

Risks

• pnpm schema evolution: mitigate with explicit supported versions,
  versioned parsers, fixtures, and intentional migrations.
• semantic drift: mitigate with differential tests against the exact pinned
  pnpm implementation.
• lifecycle-script impurity: mitigate with explicit trust policy, sandboxing,
  network denial, and complete action keys.
• platform leakage: mitigate by resolving predicates against declared target
  and execution platforms rather than the client host.
• filesystem assumptions: test realpath, symlink, executable, case
  sensitivity, and read-only package behavior on every supported platform.
• fine-grained graph overhead: measure package-node analysis, CAS lookup, and
  materialization overhead at large workspace scale before fixing granularity.
• dual developer/build layouts: maintain pnpm differential tests and clear
  diagnostics until BSMR's materializer is the single frozen-build path.

Success criteria

This RFC is complete when a developer can:

1. Use normal pnpm manifests and an exact pnpm toolchain to update dependencies.
2. Commit a lockfile that BSMR validates without reinterpretation.
3. Build a selected target without public network access once artifacts are
   fetched.
4. Receive sound local or remote cache hits across clean machines.
5. Inspect exactly why a package exists, where its bytes came from, what ran to
   build it, and why an action was or was not cached.
6. Encounter a precise pre-execution failure for every unsupported or
   untrusted dependency case.

The project should optimize for these outcomes, not for ownership of package
manager internals.

Prior art and references

• BSMR's
  Conan integration
  already separates package-manager resolution from BSMR-controlled package
  actions.
• Aspect
  rules_js pnpm integration
  translates pnpm-lock.yaml, fetches packages through Bazel's downloader,
  creates pnpm-compatible links, and models lifecycle hooks as actions.
• pnpm documents
  pnpm fetch as a lockfile-driven acquisition
  phase suitable for separating dependency fetching from later installation.
• pnpm's
  package manifest documentation defines its
  standard package-manager pinning and dependency policy fields.

Questions for design review

These questions should be settled before their respective implementation
milestones; they do not reopen the core boundary established by this RFC.

1. Which exact pnpm lockfile schema is the first supported contract?
2. Should BSMR expose a convenience command for lock updates, or only document
   invocation of the project-pinned pnpm?
3. What is the stable package-tree representation in BSMR's CAS?
4. Which standard pnpm lifecycle trust settings can be consumed without adding
   BSMR-specific policy?
5. What is the smallest initial JavaScript rule/provider surface that avoids
   duplicating dependency declarations in BUCK files?
6. Which representative public and Dedalus workspaces form the release-blocking
   conformance and performance corpus?