RFC: workspace task cache

[zkochan]

Cache the output of a workspace project's own scripts — files, logs, and exit code — keyed on declared inputs, reusing the artifact protocol that #20 shipped.

Depends on #23 for the task graph. That dependency is load-bearing, not cosmetic — see below. Both #23's scheduler and the protocol change this RFC asked for have since shipped, so what is left here is the key, the declarations, and the restore.

Why pnpm rather than a tool on top

Two things pnpm knows that Turborepo and Nx cannot:

• The resolved dependency graph, per project. Turborepo hashes the lockfile as a proxy, so any lockfile edit busts every project's cache. pnpm already computes and hashes each importer's actual resolved graph — calcDepStateInputKey, shipped with RFC: shared side-effects cache #20.
• A file-granular content-addressed store. Turborepo stores each task's output as its own archive; a file in ten outputs is stored ten times.

Why it needs the task graph

An earlier revision of this RFC scoped itself as cache-only and keyed a task on the same-named upstream script. That is wrong, not merely limited.

Project A's test consumes node_modules/B/dist, produced by B's build. The same-name rule keys it on B's test — including tests A does not consume, omitting the build it does. Nothing makes up the difference: link targets enter the dependency-graph hash by identity alone (graph-hasher/src/index.ts:481-486 gives them fullPkgId: linkTargetNode, children: {}, no content).

The sharp case: B has build but no test script. Then A's test key contains nothing whatsoever about B. Change B's source, rebuild, and A's test hits cache against a dist it has never seen.

With #23's dependsOn, test: ['build'] names the producing task, and its pass-through rule keeps a project that lacks a script from severing the chain. The key becomes correct by construction rather than correct by accident.

What it specifies

• The task key: identity, script text (including pre/post), declared input digests, declared env as a name-to-value map, the resolved package graph for external dependencies, and the declared upstream task keys for internal ones. Env values are hashed into the key and never recorded in provenance. The graph those upstream keys resolve through must be dependency-closed: a selection narrows which tasks are requested, never which projects the graph contains, or the key becomes a function of the invocation.
• outputs, inputs, env, and cache alongside RFC: workspace task orchestration #23's dependsOn in the same tasks section. outputs is mandatory for cacheability, and an absent key means not cacheable rather than produces nothing — RFC: shared side-effects cache #20's "absence of information is not permission" rule applied to a different field. outputs: [] is the positive assertion that lets lint be cached for its logs alone.
• Restoring into a directory the user owns, which has no precedent in RFC: shared side-effects cache #20: never hardlink from CAFS (the first writer would corrupt the shared blob), delete what the previous run left, and refuse to overwrite a file nothing accounts for.
• Two things easy to miss: a hit must replay captured logs, and a hit must still run syncInjectedDepsAfterScripts or consumers of an injected dependency see the previous build.
• The remote tier is RFC: shared side-effects cache #20 with a different subject. Owner is always organization, compatibility is usually universal, and eligibility is trivially satisfied because a workspace task is first-party.

What has since shipped

The prerequisite this RFC called out — #20's rule that the protocol must not embed package identity in the shape of a request or response key, which ArtifactCandidate and ArtifactPayload violated by requiring package and sourceIntegrity next to the opaque key — landed in pnpm/pnpm#14267 while it was still free. Both types now carry a kind-discriminated subject, and a workspace-task subject is nameable on the wire today.

#20's two then-unfinished items also shipped, and they land here unevenly: persistent quarantine (pnpm/pnpm#14259) is inherited whole and matters more for tasks than for dependencies, while lockfile pinning (pnpm/pnpm#14243) does not carry over as it stands, because a pin is recorded on a package snapshot and a workspace task has none.

#23's scheduler is merged in both stacks. The one change it still needs for this RFC is the requested-versus-contained split described above.

Open for discussion

Whether this is pnpm's scope at all is the first question, and the RFC argues the "do nothing, let Turborepo do this" alternative as a real one — including that being a remote-cache backend for Turborepo is cheap, non-exclusive, and worth doing on its own merits. Also open: what an undeclared dependsOn should key on, whether pnpm can detect a task that reads an upstream output it never declared, non-relocatable output, input-hashing cost on misses, two tasks declaring the same output root, and where a task artifact's lockfile pin would live if it has one at all.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 51 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 33feeb85-3ced-44bb-9eab-189576000c02

📥 Commits

Reviewing files that changed from the base of the PR and between 2508faf and 92abdac.

📒 Files selected for processing (1)

• text/0000-workspace-task-cache.md

---

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

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

RFC: Define content-addressed caching for workspace tasks

📝 Documentation ✨ Enhancement 🕐 40+ Minutes

AI Description

• Specifies task cache keys from declared inputs, environment, dependencies, and upstream tasks.
• Defines safe output restoration, log replay, local storage, and remote artifact reuse.
• Extends workspace task declarations with cache eligibility and input/output metadata.

Diagram

graph TD
  Config["Task declarations"] --> Graph["Task graph"] --> Key["Key builder"] --> Lookup["Cache lookup"]
  Lookup -- "cache miss" --> Runner["Task runner"] --> Store["Artifact store"]
  Lookup -- "cache hit" --> Restore["Safe restore"] --> Outputs["Workspace outputs"]
  Store --> Restore
  Runner --> Outputs

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Delegate caching to Turborepo or Nx

• ➕ Avoids expanding pnpm's product scope
• ➕ Uses mature task-cache ecosystems and cloud services
• ➖ Duplicates pnpm's dependency graph and file hashing
• ➖ Invalidates broadly on lockfile changes
• ➖ Cannot reuse pnpm's file-granular content-addressed store

2. Hash materialized workspace dependencies

• ➕ Remains correct without declared upstream task edges
• ➕ Captures actual consumed workspace package contents
• ➖ Hashes large materialized trees on misses
• ➖ Cannot isolate which upstream outputs a task consumes
• ➖ Adds repeated filesystem work compared with upstream key lookup

3. Use a project-local cache

• ➕ Simpler indexing and lifecycle management
• ➕ Matches common task-runner cache layouts
• ➖ Loses reuse across repository checkouts
• ➖ Loses file-level deduplication across tasks and projects
• ➖ Introduces a separate cache requiring garbage collection

Recommendation: Proceed with the RFC's task-graph-based key and shared content-addressed store, shipping the local tier before remote reuse. This approach uniquely uses pnpm's resolved dependency graph and storage model while avoiding stale hits from same-named-task assumptions; implementation should resolve the undeclared-edge fallback and overlapping-output-root questions before enabling caching by default.

Files changed (1) +207 / -0

Documentation (1) +207 / -0

0000-workspace-task-cache.mdSpecify workspace task caching semantics and architecture +207/-0

Specify workspace task caching semantics and architecture

• Adds an RFC for caching successful workspace task outputs, logs, and exit codes using keys derived from declared inputs and a dependency-closed task graph. It defines task configuration, local and remote artifact reuse, safe working-tree restoration, implementation sequencing, alternatives, and unresolved correctness and operational questions.

text/0000-workspace-task-cache.md