Skip to content

feat(cache): declare the platform a task depends on with cache.platform - #1004

Draft
fengmk2 wants to merge 4 commits into
mainfrom
feat/remote-cache-cross-platform
Draft

fengmk2 wants to merge 4 commits into
mainfrom
feat/remote-cache-cross-platform

Conversation

@fengmk2

@fengmk2 fengmk2 commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Motivation

Every remote key starts with a header that names the OS and the architecture, so an entry that Linux CI stores is never fetched on a developer's Mac. This is true even for a task whose outputs are the same on every platform, such as a code generator that runs on Node.js. Teams whose CI and developers use different platforms get few remote hits. Today the only workaround is a server that rewrites each key's header, which depends on the key's private encoding and applies to every task at once (#926).

Which parts of the platform a task's result depends on is a statement about the task's cache identity, like env and input. Comparable tools also model it as a declared input, not as a remote cache flag: Turborepo and Nx hash a platform file or a runtime input, and Rush has [os] and [arch] tokens in its cache entry names.

Changes

  • Config. cache.platform lists the parts of the platform that a task's outputs depend on: "os", "arch", both, or neither ([]). The workspace root's cache.platform is the default for every task and cached package.json script that doesn't set its own. With neither set, it's ["os", "arch"], so today's keys don't change.

    // workspace root
    run: { cache: { remote: { url }, platform: [] } }
    
    tasks: {
      generate: { command: 'node generate.ts' },                             // uses the workspace's: []
      'build:native': { command: 'napi build', cache: { platform: ['os', 'arch'] } },
      test: { command: 'vitest run', cache: { platform: ['os'] } },
    }

    Like the rest of remote caching, the field is parsed but left out of the public types.

  • Keys. A part that isn't listed is an empty string in the header of both remote keys (key and secondary_key). No platform has an empty OS or architecture, so such a key never equals a key that names that part. The cache schema version and the remote value format stay in the header. A fallback's key is decoded with the same header, so its miss reason still works.

  • Unchanged. The local cache doesn't depend on platform. A fetched entry is still checked against the fetching machine's inputs, and the rest of the key (the program, its arguments, its working directory, its envs, and its input and output globs) must still match. Changing a task's platform changes its remote keys once.

  • Built-in tools. A built-in tool's platform adds to the platform of the task that runs it, the same way its env does. A tool that sets nothing keeps the task's, and a tool can't remove a part that the task lists. It uses the remote cache only if both allow it.

  • Planning. The workspace default is applied at plan time in effective_cache_config, where cache.scripts and cache.tasks are already applied. CacheMetadata gets platform beside input_config and output_config.

Vite+ builds EnabledCacheConfig literals for its built-in tools, so it needs platform: None added to them when it updates.

Limits on what can share:

  • Windows. The key names the program that the command resolves to: a program outside the workspace by its file name, and a program inside it by its workspace path. Windows resolves node to node.exe and a node_modules/.bin program to its .cmd shim, so Windows entries don't match Linux or macOS entries. Linux and macOS, on any architecture, can share. A portable program identity for Windows is left for later.
  • Built-in tools. They still put absolute paths in their arguments (Cache keys record absolute pnpm-store paths through args, so built-in-tool verdicts cannot cross machines #717), so their keys can still differ between machines.

Closes #926

🤖 Generated with Claude Code

…th `cache.remote.crossPlatform`

Every remote key starts with a header that names the OS and the
architecture, so an entry that Linux CI stores is never fetched on macOS,
even for a task whose outputs are the same on every platform. A task can
now set `cache: { remote: { crossPlatform: true } }`. Its remote keys then
have an empty OS and architecture, which no platform has. The default
keys and the local cache don't change.

Closes #926

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@fengmk2 fengmk2 added the remote cache Remote caching label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

fspy benchmark

linux

dynamic/launch             change  -0.27%  [ -4.51% ..  +4.19%]  overhead   +59.32%
dynamic/access             change  +0.85%  [ -5.56% .. +13.24%]  overhead   +19.43%
dynamic/access-relative    change  +0.85%  [ -6.50% .. +20.34%]  overhead   +68.53%
dynamic/access-contended   change  +1.62%  [ -6.39% .. +14.90%]  overhead    +9.40%
static/launch              change  -0.06%  [ -4.62% ..  +4.65%]  overhead  +190.27%
static/access              change  -0.47%  [ -2.77% ..  +1.74%]  overhead +1429.13%
static/access-relative     change  -0.55%  [ -1.77% ..  +1.34%]  overhead +1970.06%
static/access-contended    change  -0.27%  [ -1.31% ..  +0.80%]  overhead +2060.69%

macos

dynamic/launch             change  +0.22%  [ -2.89% ..  +2.71%]  overhead  +227.39%
dynamic/access             change  -0.38%  [ -4.49% ..  +3.16%]  overhead    +3.21%
dynamic/access-relative    change  +0.56%  [ -1.65% ..  +3.70%]  overhead  +264.51%
dynamic/access-contended   change  +0.84%  [ -1.85% ..  +2.98%]  overhead    +2.63%

windows

dynamic/launch             change  -0.09%  [ -1.31% ..  +1.35%]  overhead   +26.62%
dynamic/access             change  -0.56%  [ -1.68% ..  +0.38%]  overhead    +1.14%
dynamic/access-relative    change  +0.54%  [ -1.54% ..  +4.15%]  overhead    +3.83%
dynamic/access-contended   change  +1.49%  [ -7.86% .. +17.89%]  overhead    +4.19%

fengmk2 and others added 2 commits November 20, 2026 22:50
…gram

The key names a program outside the workspace by its file name and a
program inside it by its workspace path. Windows resolves `node` to
`node.exe` and a `node_modules/.bin` program to its `.cmd` shim, so
Windows entries don't match Linux or macOS entries even with
`crossPlatform`.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@fengmk2
fengmk2 requested a review from wan9chi November 21, 2026 08:06
@fengmk2
fengmk2 marked this pull request as ready for review November 21, 2026 08:06
@fengmk2
fengmk2 marked this pull request as draft November 21, 2026 08:08
…orm`

Replace `cache.remote.crossPlatform` with `cache.platform`, a list of the
parts of the platform (`"os"`, `"arch"`) that a task's outputs depend
on. The workspace root's `cache.platform` is the default for every task
and cached script that doesn't set its own, so package.json scripts can
share entries too. The default is `["os", "arch"]`, so keys don't change
unless a task or the workspace opts in.

A part that isn't listed is empty in the remote key header. A built-in
tool's `platform` adds to the task's, so a tool can't remove a part that
the task lists. A task's `cache.remote` goes back to a boolean.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@fengmk2 fengmk2 changed the title feat(cache): share a task's remote cache entries between platforms with cache.remote.crossPlatform feat(cache): declare the platform a task depends on with cache.platform Nov 21, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

remote cache Remote caching

Projects

None yet

1 participant