pnpm workspaces and lockfile discipline

A lockfile is present, but the clean offline install still fails

A two-package pnpm workspace installs successfully on a developer machine. Then two independent changes are introduced: one package manifest drifts without a matching lockfile update, and one required package artifact is removed from the prepared local store. A warm repeat install can hide the second problem because old state may still be available.

Your deliverable is pnpm Dependency Closure Record v1. It keeps four questions separate: which dependency is required to stay local to the workspace, whether current manifests agree with pnpm-lock.yaml without mutating it, whether the bounded local artifact store is sufficient for a clean offline reconstruction, and which runtime/tool identity was actually tested.

The claim is deliberately limited. A successful record does not prove operating-system closure, native-library closure, build correctness, or bit-for-bit reproducibility.

Three routes, one evidence bar

On the Foundation route, make the boundaries explicit before running commands: workspace membership, manifest intent, lock consistency, local artifact availability, and clean installed state. On the Repair route, isolate one misconception and rerun only the probe that distinguishes it. On the Experienced / Fast Path, skip command walkthroughs but not hashes, clean-state evidence, mutation response, or residual risk.

Before each probe, state the question. Examples: “Will this dependency resolve only to a local workspace package?”, “Can these manifests be accepted without changing the lock?”, and “Can this clean target be reconstructed using only the prepared store?” The command is evidence for that question, not a universal certificate.

Mental model: Manifest → Lockfile → Store → clean installed tree

Keep the evidence chain explicit:

1. Workspace manifest layer. pnpm-workspace.yaml selects the workspace, while package manifests declare dependency intent. workspace: is a pnpm-specific way to require a dependency to resolve to a local workspace package.
2. Lock consistency layer. pnpm-lock.yaml records the resolved dependency state. An explicit frozen install checks that installation can proceed without generating or updating the lockfile; manifest/lock drift fails this gate.
3. Artifact availability layer. Offline mode restricts installation to packages already available locally. A consistent lock can still be insufficient if a required artifact is absent from the prepared store.
4. Clean installed-state layer. A warm node_modules or store can conceal missing inputs. The assessed reconstruction starts from a controlled clean target and named store boundary.
5. Environment identity. Record pnpm and runtime identity. The lockfile does not, by itself, pin every OS, runtime, native library, registry, or build input.

These layers are related, but none is a substitute for another.

Build pnpm Dependency Closure Record v1

For each material dependency or probe, record at least: workspace_member, manifest_hash, dependency_intent, lock_hash, lock_consistent, store_boundary, offline_clean_result, failure_layer, pnpm_identity, runtime_identity, evidence, and residual_boundary.

Use evidence states precisely:

• OBSERVED: directly obtained from a file, hash, command output, or controlled fixture;
• INFERRED: a bounded conclusion derived from observations;
• UNKNOWN: required evidence is missing or contradictory.

Do not refresh the lockfile during a verification that is supposed to test whether the existing lock is consistent. Updating the lock can be a legitimate development action, but it destroys the evidence for the old frozen-consistency question.

Frozen and offline answer different questions

Current pnpm 12.x documentation describes workspace: as a protocol that refuses to resolve to anything other than a local workspace package. That makes local intent testable: if the required local package/version is unavailable, installation fails instead of silently substituting a registry package.

The same official documentation defines --frozen-lockfile as a no-lock-update installation mode that fails when the lockfile is out of sync with the manifest, when an update is needed, or when the lockfile is missing. Use the explicit flag in the lab rather than depending on environment-specific defaults.

--offline answers a different question: pnpm uses only packages already available in the store, and installation fails if a required package is not available locally. Therefore “frozen passes” does not imply “offline clean reconstruction passes,” and “offline succeeds on my warm machine” does not prove that a controlled clean target has complete local artifacts.

Worked example: one drift failure, one artifact failure

Baseline. The workspace contains apps/cli and packages/core. apps/cli depends on @closure/core through workspace:*. The manifest hashes, lock hash, pnpm/runtime identity, and prepared store boundary are recorded. A clean install is attempted with explicit frozen and offline constraints. If it succeeds, the bounded conclusion is that this exact manifest/lock/store/tool context reconstructed successfully.

Manifest-drift mutation. Change a dependency range in a manifest but keep the lockfile unchanged. The expected failure layer is LOCK_CONSISTENCY: the verification must not “repair” the lock during this test.

Missing-artifact mutation. Restore the baseline manifests and lock, then remove one required item from the prepared store boundary. The lock can remain consistent while the clean offline reconstruction fails. The expected failure layer is OFFLINE_ARTIFACT_AVAILABILITY.

The two failures are not interchangeable. Recording only “install failed” loses the evidence boundary.

Four shortcuts that corrupt closure evidence

“The committed lockfile proves offline reproducibility.” Repair: test a clean offline reconstruction against a named local store boundary.

“Frozen means use the lock even when manifests disagree.” Repair: make one manifest drift and verify that the frozen gate refuses a lock update rather than silently accepting the mismatch.

“It works on my machine, so the closure is complete.” Repair: reset the install target and separate warm state from the prepared store being claimed.

“workspace: is just cosmetic version syntax.” Repair: remove or rename the required workspace member and observe that local-workspace intent cannot be satisfied by a registry substitution.

For experienced engineers: make dependency verification reviewable

In a real repository, keep lock refresh and lock verification as separate review events. When a dependency change legitimately requires a new lock, generate it in an explicit change and review the resulting diff. When the question is whether a committed state reconstructs, use a non-mutating frozen check.

For offline or air-gapped preparation, name the artifact boundary being tested. A store prepared on one machine is not automatically evidence for every platform or native dependency. Record runtime/tool identity and any native/OS boundaries that remain outside the lesson claim.

A CI success is valuable evidence, but only for the environment and inputs that CI actually exercised. The closure record should make those boundaries visible instead of converting one green job into a universal guarantee.

Strict verification costs convenience, and that is the point

A normal development install may reasonably update the lock when dependency intent changes. A frozen verification intentionally rejects that convenience so drift becomes visible. Offline verification further constrains acquisition and therefore needs a prepared artifact boundary.

These constraints are not a recommendation that every developer work offline all the time. They are evidence tools. Use them when the engineering question is reproducibility or inspectability of a committed dependency state, and keep broader toolchain closure for later lessons.

Lab: baseline, then one mutation at a time

Use the local fixture in TOL002-LAB1. Start each independent run with python setup_fixture.py; this reset acts only inside the packaged lesson fixture. The learner surface contains the workspace declarations, manifests, lock snapshot, a real packaged local tarball with recorded integrity, reset/mutation tools, and an execution plan for pnpm. The probe provisions a named fixture-local isolated pnpm store from that tarball before the frozen/offline install; it never treats a host/global store as the assessed boundary. No credentials or privileged host changes are required.

First record the baseline hashes and bounded execution context: resolved tool/runtime identity, platform, cwd, artifact integrity, and the explicit fixture-local store path. Reset the target, then run the frozen/offline probe in the environment where pnpm is available. Next run three mutations independently: manifest drift without a lock update, deletion of one prepared local artifact, and removal/rename of one workspace member referenced through workspace intent. Reset between mutations.

For each run, classify only the smallest supported failure layer. The transfer fixture changes both manifest state and artifact availability; no command sequence is supplied as the answer. Decide whether the evidence supports LOCK_DRIFT, ARTIFACT_UNAVAILABLE, WORKSPACE_LOCAL_RESOLUTION, more than one layer, or DEFER because evidence is incomplete.

Minimum defensible evidence

A defensible closure record contains manifest and lock hashes, explicit pnpm/runtime identity, a named clean target and local store/artifact boundary, the exact frozen/offline probe, mutation evidence, and a bounded decision. Warm-state success alone is insufficient.

If declared state and observed output contradict each other, do not force a conclusion. Preserve the contradiction and reduce the probe. If pnpm itself is unavailable in the execution environment, record that as missing runtime evidence rather than substituting a simulated success.

The final statement must say what was demonstrated and what was not. For example: “This workspace/lock/store snapshot reconstructed under the recorded pnpm/runtime context; OS-native closure and build correctness were not tested.”

Assessment: diagnosis, decision, application, and transfer

AS1 — Diagnosis: A learner says the lockfile guarantees a clean offline install. Identify the smallest missing evidence boundary and the observation that would decide it.

AS2 — Decision: Given manifest/lock hashes and a successful warm install but no clean offline probe, decide ACCEPT, REJECT, or DEFER for pnpm Dependency Closure Record v1 and state the residual risk.

AS3 — Application: Execute the baseline fixture, produce the closure record, then run the manifest-drift and missing-artifact mutations without mutating the lock during verification.

AS4 — Transfer: On the changed fixture, determine whether failure is caused by lock drift, artifact unavailability, workspace-local resolution, or multiple independent boundaries. State what remains unproven.

Critical dimensions are workspace-local resolution, manifest-lock consistency, offline artifact sufficiency, clean-state verification, and scope of the reproducibility claim.

Source and freshness boundary

Tool-specific claims are bounded to current official pnpm documentation. On 2026-09-08, the pnpm 12.x workspace page still documents the root workspace configuration and workspace: local-only resolution constraint. The install page still documents explicit --frozen-lockfile no-update/out-of-sync failure behavior and --offline store-only behavior.

The Bible review-due signal remains 2026-10-17. Exact defaults and implementation details can change, so the lesson uses explicit flags and records pnpm/runtime identity instead of assuming environment defaults. No same-named flag semantics are generalized to other package managers.