@vzn/vx 0.0.636 → 0.0.637

package/docs/caching.md

@@ -31,11 +31,18 @@ opt _out_ via `cache: false`. We chose the strictest of the three.
 
 ## Cache key derivation
 
+Core keys no package file: no `package.json`, lockfile or install
+setting is a part of its own. A `package.json` keys a task as an input
+it lists (step 10), a lockfile or install setting as a plugin's key
+material (step 9); `@vzn/vx-lockfile`'s `pnpm()`, `bun()`, `npm()` and
+`yarn()` add both. Without a lockfile plugin an install moves no key, so
+a JS workspace declares one (`vx init` and `@vzn/vx-migrate` write it).
+
 The cache key for one task is a **16-hex xxHash3 digest**, seed-chained
 over (in order):
 
 1. **`CACHE_VERSION`** — the key-derivation sentinel
-   (currently `'vx-cache-v42'`, in `src/cache/key-fold.ts`). Bumped when
+   (currently `'vx-cache-v43'`, in `src/cache/key-fold.ts`). Bumped when
    the key derivation or the artifact container changes, or stored bytes
    are wrong under an unchanged key. See
    [§ Bumping CACHE_VERSION](#bumping-cache_version).
@@ -43,54 +50,7 @@ over (in order):
    identical everything else still produce distinct keys — protects
    against e.g. `pkg-a#build` accidentally cache-hitting on a
    `pkg-b#build` entry.
-3. **Workspace fingerprint** — xxh3 of every supported workspace
-   marker found at the root (see
-   [`modules/fingerprint.md`](./modules/fingerprint.md)):
-   `pnpm-lock.yaml`, `package-lock.json`, `npm-shrinkwrap.json`,
-   `yarn.lock`, `bun.lock`, `bun.lockb`, `pnpm-workspace.yaml`,
-   `.yarnrc.yml` (Yarn 4 catalogs, which `yarn.lock` does not record),
-   `.npmrc` and `bunfig.toml` (install settings no lockfile records),
-   and the content of each patch the Bun lockfile names under
-   patchedDependencies (it records a patch by path alone). Any
-   install-resolved change (a `bun install` that bumps `bun.lock`) or
-   any workspace-shape change invalidates _every_ cache entry. This is
-   the single global "the world changed" lever — and a plugin can take
-   one file off it: `VxPlugin.fingerprint` claims a lockfile, core
-   leaves it out of this digest, and the plugin's `key` hook folds what
-   the file means for each project instead (`@vzn/vx-lockfile`'s `pnpm()`
-   folds the project's own resolved dependency closure and the root
-   package's, so `pnpm update foo` re-keys only the projects that depend
-   on `foo` — every project when the root does, since the root's tools
-   run from the root `node_modules/.bin` on every task's PATH; its `bun()` is the same
-   for `bun.lock`, and this repo declares that one). The
-   config-evaluation cache still keys on every file: a config may import
-   a dependency the lockfile resolved.
-
-   The fingerprint is read once per run, before any task. A task in the
-   root project may rewrite one of these files — `pnpm install` without
-   `--frozen-lockfile` updates the lockfile and the installed tree — and
-   every key taken before it names the old one. So a task that may
-   (unsandboxed in the root project, or granted a write over one) tells
-   the run when its command ran, the run re-checks the files then (one
-   `stat` each, following a symlink as both reads do — an `lstat` missed
-   a lockfile rewritten through a link, item 760 — the bytes compared
-   for any written since the read), and
-   once one moved nothing keyed on the old digest is probed or saved for
-   the rest of the run, with one status line naming the file. Every
-   reader after such a task is keyed late, not up front. Without it the
-   run after a lockfile rewrite restored a build made against the old
-   install, and a save filed a build against the new install under the
-   old lockfile's key, replayed whenever the tree went back (item 750,
-   [`modules/fingerprint-watch.md`](./modules/fingerprint-watch.md)).
-
-4. **Project `package.json` hash** — the git blob OID of the project's
-   `package.json`: the index OID when the file is tracked and clean,
-   else `cache.hashFile`'s blob OID of the worktree bytes (empty when
-   there is none). Folded in implicitly (Turbo / Nx parity).
-   Covers the case where `cache.inputs.files: ['src/**']` is narrow
-   and a `package.json` dep change would otherwise leak undetected.
-   (Added at v12; rationale in [§ History](#history).)
-5. **Task config hash** — `xxh3(JSON.stringify(hashableConfig(node.config)))`
+3. **Task config hash** — `xxh3(JSON.stringify(hashableConfig(node.config)))`
    of the _evaluated_ task config. The projection is one field wide:
    `exec.remote` is dropped, because it says WHERE a task runs and not
    what it does (§ What's NOT in the key). Captures:
@@ -107,55 +67,87 @@ over (in order):
      `process.env`-read at config-load time injected. Bun's native
      `await import()` evaluates the module and bakes those values into
      the object before we serialize.
-6. **`forwardArgs`** — CLI args passed after `--`. Folded into the
+4. **`forwardArgs`** — CLI args passed after `--`. Folded into the
    key so `vx run test -- --watch` doesn't cache-hit a previous
    `vx run test`. Scoped to the user-requested tasks only — dependsOn-
    pulled deps don't see them (their cache identity stays clean) — and
    to a command: a requested default `build` runs none and folds none
    (X-119).
-7. **`cache.inputs.env` resolved values** — `[name, value]` pairs
+5. **`cache.inputs.env` resolved values** — `[name, value]` pairs
    read from host `process.env` at hash time (delimited `name\0value`
    so boundaries are unambiguous). Listed names get their current
    values; an unset name folds its bare name, with no `\0`, so unset
    and set-to-empty are two keys (the child tells them apart:
    `passThrough` leaves an unset name out). A name holding a NUL is
    refused at load.
-8. **`cache.inputs.runtime` resolved output** — `[command, output]`
+6. **`cache.inputs.runtime` resolved output** — `[command, output]`
    pairs, where `output` is the trimmed stdout of each command run via
    `sh -c` in the **project dir** at hash time; a command with stderr
    (or a NUL in stdout) folds `\0<stdout length>\0<stdout><stderr>`,
    so bytes moved between the streams move the key.
-   The runtime-output analog of step 7: the command _strings_ are in
-   the resolved config (step 5), their _output_ is resolved live every
+   The runtime-output analog of step 5: the command _strings_ are in
+   the resolved config (step 3), their _output_ is resolved live every
    run. Folded with the command count + each `command\0output` pair.
-9. **`cache.inputs.workspaceRuntime` resolved output** — same as step
+7. **`cache.inputs.workspaceRuntime` resolved output** — same as step
    8 but commands run at the **workspace root**, and the pairs fold
    into a **distinct namespace** (`ws-runtime-values:`) so an identical
    `(command, output)` never aliases the project-cwd `runtime` values.
-10. **Filtered upstream task cache hashes** — every upstream task's
-    own cache key, filtered by `cache.inputs.tasks` (default: all of
-    them). Sorted by hash before folding so the ordering of `dependsOn`
-    doesn't change the key. This is the cascade mechanism: if anything
-    beneath you changes, your hash changes too. The set is `dependsOn`'s,
-    never the run's selection: a dependency `--exclude-dependencies`
-    keeps from running is still folded, with the key a full run would
-    derive for it (nx#35234), so the flag moves no key. Its outputs are
-    whatever is on disk, which nothing proves current, so a task whose
-    key folds one, and everything built on it, may hit but does not
-    save (`orchestrator/excluded-keys.ts`); a task with
-    `cache.inputs.tasks: []` folds none and saves as usual.
-11. **Plugin key material** — the `{ name: value }` pairs a plugin's
-    `key(task, ctx)` stage returned for this task, stored on the node as
-    sorted `plugin/name` pairs and folded after the upstream keys and BEFORE the input files,
-    ONLY when non-empty — so a workspace with no `key` plugin derives
-    byte-identical keys to one before the stage existed (no
-    `CACHE_VERSION` bump when it shipped). `vx why` names a changed pair
-    as `plugin <plugin>/<name>`. Two plugins of one package (a plugin's
-    name is its package's) that return one name are told apart as
-    `<name>`, `<name>#2`, … in value order, so declaration order still
-    keys nothing (item 1028).
-
-12. **Input files' content hashes** — `cache.inputs.files` resolved to
+8. **Filtered upstream task cache hashes** — every upstream task's
+   own cache key, filtered by `cache.inputs.tasks` (default: all of
+   them). Sorted by hash before folding so the ordering of `dependsOn`
+   doesn't change the key. This is the cascade mechanism: if anything
+   beneath you changes, your hash changes too. The set is `dependsOn`'s,
+   never the run's selection: a dependency `--exclude-dependencies`
+   keeps from running is still folded, with the key a full run would
+   derive for it (nx#35234), so the flag moves no key. Its outputs are
+   whatever is on disk, which nothing proves current, so a task whose
+   key folds one, and everything built on it, may hit but does not
+   save (`orchestrator/excluded-keys.ts`); a task with
+   `cache.inputs.tasks: []` folds none and saves as usual.
+9. **Plugin key material** — the `{ name: value }` pairs a plugin's
+   `key(task, ctx)` stage returned for this task, stored on the node as
+   sorted `plugin/name` pairs and folded after the upstream keys and BEFORE the input files,
+   ONLY when non-empty — so a workspace with no `key` plugin derives
+   byte-identical keys to one before the stage existed (no
+   `CACHE_VERSION` bump when it shipped). `vx why` names a changed pair
+   as `plugin <plugin>/<name>`. Two plugins of one package (a plugin's
+   name is its package's) that return one name are told apart as
+   `<name>`, `<name>#2`, … in value order, so declaration order still
+   keys nothing (item 1028).
+
+   A plugin that reads a root file claims it (`VxPlugin.fingerprint`).
+   `@vzn/vx-lockfile`'s `pnpm()` folds the project's own resolved
+   dependency closure from `pnpm-lock.yaml` and the root package's, so
+   `pnpm update foo` re-keys only the projects that depend on `foo` —
+   every project when the root does, since the root's tools run from the
+   root `node_modules/.bin` on every task's PATH; `bun()`, `npm()` and
+   `yarn()` are the same for their lockfiles (`npm()` reads
+   `npm-shrinkwrap.json` over `package-lock.json`, as npm does; `bun()`
+   refuses a `bun.lockb` with no `bun.lock`, which it cannot read), and
+   this repo declares `bun()`. Each also claims its manager's install
+   settings (`pnpm()`: `pnpm-workspace.yaml`, `.npmrc`; `bun()`:
+   `bunfig.toml`, `.npmrc`; `npm()`: `.npmrc`; `yarn()`: `.yarnrc.yml`)
+   and folds each whole into every task.
+
+   The run reads each claimed root file once, before any task. A task
+   in the root project may rewrite one — `pnpm install` without
+   `--frozen-lockfile` updates the lockfile and the installed tree — and
+   every key taken before it names the old one. So a task that may
+   (unsandboxed in the root project, or granted a write over one) tells
+   the run when its command ran, the run re-checks the claimed files
+   then (one `stat` each, following a symlink as both reads do — an
+   `lstat` missed a lockfile rewritten through a link, item 760 — the
+   bytes compared for any written since the read), and once one moved
+   nothing keyed on the old bytes is probed or saved for the rest of the
+   run, with one status line naming the file. Every reader after such a
+   task is keyed late, not up front. Without it the run after a lockfile
+   rewrite restored a build made against the old install, and a save
+   filed a build against the new install under the old lockfile's key,
+   replayed whenever the tree went back (item 750,
+   [`modules/fingerprint-watch.md`](./modules/fingerprint-watch.md)).
+   With nothing claimed, no root file is read or watched.
+
+10. **Input files' content hashes** — `cache.inputs.files` resolved to
     a concrete list of project-relative paths (gitignore-aware,
     declared-outputs-excluded, nested-projects-excluded), each file
     contributing its **git blob OID** (v20). On a clean tree the OID
@@ -225,7 +217,7 @@ add` under a clean filter (`core.autocrlf=true`, a `text` rule)
     and every project under it is selected.
 
     A task with **no `cache` block** derives a key too — its dependents
-    fold it (step 10) — and, declaring nothing, folds **every file in
+    fold it (step 8) — and, declaring nothing, folds **every file in
     its project**: `**/*`, gitignore-aware, untracked files included,
     and its own outputs not excluded, since it declared none. So its
     key moves whenever it writes a file git does not ignore: a cached
@@ -238,8 +230,7 @@ add` under a clean filter (`core.autocrlf=true`, a `text` rule)
 
     Declaring nothing, such a task may also have **written** anywhere
     in its project, so what the run learned about that project at its
-    start — the git listing, the index OIDs, the `package.json` digest
-    — is dropped once its command exits, pass or fail, and a later key
+    start — the git listing and the index OIDs — is dropped once its command exits, pass or fail, and a later key
     re-lists and hashes by content. For the same reason a task after it
     in the same project (`dependsOn`, even with `tasks: []`) is never
     keyed up front by the local short-circuit or the remote prefetch.
@@ -562,7 +553,7 @@ Hard invariants of the remote prefetch:
   later `get` finds it as a now-local hit — still reports
   `source: 'remote'`, so the outcome is `cache-hit-remote`.
 - **A remote-read-off policy** (`--no-cache`, `--force`, or
-  `--cache=remote:`) fires no prefetch.
+  `--cache-policy=remote:`) fires no prefetch.
 - **Never fail.** Every remote path (get / put / ingest / prefetch)
   catches all errors and degrades to a cache miss. A remote 500, a
   network drop, a corrupt artifact, or a failed integrity check can
@@ -606,8 +597,7 @@ Caching is controlled by a four-axis `CachePolicy` — **localRead**,
 **localWrite**, **remoteRead**, **remoteWrite** — independent toggles,
 each enforced inside the matching cache layer at construction time. The
 local `Cache` gets a `{ read, write }` slice gating its task artifact
-get/save, the config-evaluation cache's reads and writes, and the
-file-hash memo's writes (never `recordRun` / `stats` / `prune` / ingest
+get/save and the file-hash memo's writes (never `recordRun` / `stats` / `prune` / ingest
 / key derivation); the `LayeredCache` additionally gates its own remote
 read-through (`remoteRead`), upload (`remoteWrite`), and prefetch
 (`remoteRead`). The orchestrator derives two booleans per task:
@@ -623,14 +613,23 @@ restore, no output clean, no local save), and its result lives in the
 remote executor's own store.
 
 The CLI maps three flags to a policy (precedence: start all-on → apply
-`--cache` → `--no-cache` forces all off → `--force` forces both reads
+`--cache-policy` → `--no-cache` forces all off → `--force` forces both reads
 off): `--no-cache` = everything off (no read, no write, no output
 clean); `--force` = reads off / writes on (re-execute and refresh the
-cache, outputs cleaned); `--cache=<spec>` = explicit per-layer control.
-See `docs/cli.md` § Cache control.
+cache, outputs cleaned); `--cache-policy=<spec>` = explicit per-layer control.
+Off CI, unless a spec names the remote, `remoteWrite` starts off: a key
+holds only declared inputs, so a laptop's undeclared tool or file could
+replay on CI. See `docs/cli.md` § Cache control.
+
+The setup we recommend for a shared remote: the write token only in the
+default branch's CI (a protected environment), a read-only token on
+laptops and in pull request jobs, and `cache.scope` (`github()` sets it)
+so a PR's own writes, when its token allows them, land apart. The token
+is the boundary; the policy and the scope are the client's half
+(`docs/security.md` § Cache poisoning).
 
 One subtlety: when `localWrite` is off but `remoteWrite` is on
-(`--cache=local:,remote:rw`), there's no on-disk artifact for the
+(`--cache-policy=local:,remote:rw`), there's no on-disk artifact for the
 `LayeredCache` to read before uploading — so it packs the tar.zst bytes
 in memory (`Cache.packArtifactBytes`) and uploads those.
 
@@ -684,8 +683,8 @@ before the command ran — at the task's start, or up front by the local
 short-circuit — and the save files the outputs under it, so the inputs
 must still be what it describes. Two checks, in order. The key
 re-derived just before the command (`describeTaskInputs`, which the
-executor seam needs anyway) must equal it. Then each input file and the
-project's `package.json` is `lstat`ed once: a file whose ctime falls
+executor seam needs anyway) must equal it. Then each input file is
+`lstat`ed once: a file whose ctime falls
 after, or within `FILE_HASH_RACY_MS` before, the moment its digest was
 learned — the enumeration's start for an index OID, the describe for a
 hashed file — is hashed again and compared, and a file that is gone has
@@ -698,9 +697,9 @@ edit, was filed under the key and restored over the original (item
 one status line names the file (``[vx] app#format: `packages/app/a.ts`
 changed after its key was taken — …``), and the run forgets what it
 knew about the project, as after an uncached task (§ Cache key
-derivation, step 12). This covers a formatter rewriting its own input
+derivation, step 10). This covers a formatter rewriting its own input
 (turborepo#10111) and a user's edit mid-run (turborepo#1146). A task
-left remote (`--download=none`) is held to the same checks: a moved
+left remote (`--cache-download=none`) is held to the same checks: a moved
 key still lets a local consumer fetch its outputs, but the fetch saves
 no entry; until X-123 it saved them under the old key. A task
 that rewrites its own input to the SAME bytes (`sed -i` always writes)
@@ -713,7 +712,10 @@ task of the same project running alongside can change an input and put
 it back. A task that rewrites its own input to identical bytes (tsdown's
 `package.json`) sets `cache.inputStability: { strategy: 'mutable' }`, and a write
 during its command is then judged by its bytes, as an earlier write is;
-different bytes still withhold the entry. `VX_INPUT_STABILITY=mutable`
+different bytes still withhold the entry, and so does a write made while
+another command that may write the file ran (`command-windows.ts`: one
+in the same project, or one with a write grant elsewhere in the
+workspace), named on the line as `while <task> ran`. `VX_CACHE_INPUT_STABILITY_STRATEGY=mutable`
 makes that the default (owner, 2026-10-12); `'unchecked'` skips the
 check, and `severity: 'error'` fails the task instead of warning
 (`docs/schema.md`). A file ADDED under an
@@ -737,14 +739,14 @@ transitively: that key does not name the bytes they built from (`[vx] app#use: r
 over app#gen's outputs, which its key no longer describes — …`). Until
 2026-09-27 (A-12) they saved, and once the input was put back they hit
 the edit's output.
-A workspace fingerprint a task rewrote since the run read it (§ Cache
-key derivation, step 3) withholds the save the same way, and no key
+A claimed root file a task rewrote since the run read it (§ Cache key
+derivation, step 9) withholds the save the same way, and no key
 taken before it is probed or restored: a hit the up-front probe found
 goes back to the scheduler and runs once its deps are done. Until X-124
 that hit restored the old install's bytes.
 
 A miss that ran here and saves **nothing** — it failed, the cache
-policy writes nothing (`--cache=local:r,remote:r`), an upstream failed
+policy writes nothing (`--cache-policy=local:r,remote:r`), an upstream failed
 under `--continue` — runs the same input re-check and, when an input
 moved, forgets the project as above; otherwise its declared outputs are
 resolved and marked in the git snapshot exactly as a save marks them.
@@ -807,25 +809,40 @@ Declared `cache.outputs.files` are wiped in two distinct places:
   list instead of walking again: nothing is awaited between them (X-161).
 
 Both branches use the same `cleanOutputs` helper (`src/cache/inputs.ts`)
-with the same boundary rules, and two directories stay off the wipe
-whatever the glob: `.git` and `.vx` (`OUTPUT_NEVER`). `node_modules` is
+with the same boundary rules, and vx's own paths stay off the wipe
+whatever the glob: `.git`, `.vx` and each `vx.lock.json` (`OUTPUT_NEVER`;
+`.vx` holds the workspace config and the lock, which a clean deleted and a
+hit restored stale while `.vx/cache` alone was listed). `node_modules` is
 off it too unless a glob names it (`node_modules/**`, an install task's
 legitimate output); until 2026-09-27 (A-13) `**/*.js` cleaned every
 installed `.js`, and a `workspaceFiles` output glob reached even `.git`.
-A task that fails while a git-tracked file another task's clean removed
-is still missing gets one line naming the file and that task: vx cleans
-before a run where Turbo does not, so a reader with no edge to the
-producer of a committed output fails naming only the file (A-48,
-vueuse's `metadata/index.json`).
+No clean deletes a file git tracks (owner, 2026-10-14). Under an output
+glob it is still an output: the task may rewrite it (TanStack Router's
+committed `routeTree.gen.ts`), the artifact saves the bytes the run left,
+and a restore writes them. It also stays in the task's key, even under its
+own output glob, so an edit moves the key and the saved bytes follow from
+it; the task's rewrite is no input that moved mid-run. Until then the
+clean deleted a committed file under an output, and a reader with no edge
+to its producer failed naming only the file (A-48, vueuse's
+`metadata/index.json`). Untracked files under the glob are cleaned as
+before. Paths compare as
+git compares them: case-folded under `core.ignorecase` (macOS), and a
+file inside a submodule counts as committed.
 Workspace outputs take the same rules, and a path an output `!` entry
 takes back (A-44) is off the wipe, the artifact and the restore alike.
 Skipped when:
 
 - `cache.outputs.files` is empty (nothing declared as output).
 - The task's `willWrite` is false — no write axis is enabled (e.g.
-  `--no-cache`, or a read-only `--cache=local:r`). The user is debugging
+  `--no-cache`, or a read-only `--cache-policy=local:r`). The user is debugging
   and managing the tree, so vx leaves it alone. `--force` keeps writes
   on, so it DOES clean (the saved snapshot must be clean).
+- `cache.outputs.clean` is `false` (on the task, else the workspace's
+  `cache.outputs.clean`): the command sees last run's outputs (tsc's
+  `.tsbuildinfo`). The first attempt stamps what it finds instead;
+  if the run leaves any old file unchanged, nothing is cached, so no
+  entry holds a file this run did not write. A retry cleans as usual; a hit still
+  cleans before its restore.
 
 A declared output the process cannot remove (a `dist/` another user
 wrote, a read-only checkout) fails the task with `cannot remove declared
@@ -851,7 +868,7 @@ function of the cache key.
 Two cached tasks whose declared outputs overlap are refused at graph
 build. By default that holds even when one depends on the other: the
 workspace rule `rules.exclusiveOutputs` (on unless set to `false` in
-`vx.workspace.ts`, X-53) keeps one path to one task, and its refusal says
+`.vx/workspace.ts`, X-53) keeps one path to one task, and its refusal says
 how to turn it off. The shape below is correct, only slower: a stamp
 before every run, a diff after, and a clean by rows. Give each task its
 own output path where you can (`dist-individual` beside `dist`).
@@ -895,28 +912,28 @@ the next warm run; the design note keeps that shape out of scope.
 
 A task's cache becomes invalid when any of these change:
 
-| Trigger                                                                                                                                  | Mechanism                                                                                                                                                                                       |
-| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Edit a file in the task's `inputs.files` set                                                                                             | step 12 of key derivation                                                                                                                                                                       |
-| Edit a file in the task's `inputs.workspaceFiles` set (root-anchored; may live in ANY project's dir — the documented boundary exception) | step 12 — resolved workspace files join the same input-file list                                                                                                                                |
-| Any package manager updates a lockfile (`pnpm`, `npm`, `yarn`, `bun`)                                                                    | step 3 (workspace fingerprint) — or, for a lockfile a plugin claims, that plugin's `key` material (`@vzn/vx-lockfile`: only the projects whose dependency closure moved)                        |
-| Edit `pnpm-workspace.yaml`                                                                                                               | step 3                                                                                                                                                                                          |
-| Edit `package.json`'s `workspaces` field                                                                                                 | not step 3 — membership: a project that joins or leaves changes which projects exist and which nested dirs its parent's globs exclude (step 12); the file itself is hashed per project (step 4) |
-| Edit the project's `package.json` (dep / version / scripts change)                                                                       | step 4 (project package.json hash)                                                                                                                                                              |
-| Edit the task's `vx.config.ts`                                                                                                           | step 5 (task config hash)                                                                                                                                                                       |
-| Edit a config file that the task config imports                                                                                          | step 5 (configHash sees the resolved object after Bun evaluates imports)                                                                                                                        |
-| Change CLI `forwardArgs` (after `--`)                                                                                                    | step 6                                                                                                                                                                                          |
-| Change a `cache.inputs.env` host value                                                                                                   | step 7                                                                                                                                                                                          |
-| Change the combined stdout+stderr of a `cache.inputs.runtime` command (resolved at hash time)                                            | step 8                                                                                                                                                                                          |
-| Change the combined stdout+stderr of a `cache.inputs.workspaceRuntime` command (resolved at hash time)                                   | step 9                                                                                                                                                                                          |
-| Upstream task's cache key changes (because its inputs changed)                                                                           | step 10                                                                                                                                                                                         |
-| Bump `CACHE_VERSION`                                                                                                                     | step 1 — orphans every entry                                                                                                                                                                    |
-| Change `exec.env.passThrough` _values_ alone                                                                                             | **NOT a trigger** by design — passThrough values are host-specific                                                                                                                              |
-| Change a file not in `inputs.files` / `inputs.workspaceFiles`                                                                            | **NOT a trigger** by design — declare it explicitly                                                                                                                                             |
-| Edit `vx-lock.json`                                                                                                                      | **NOT a trigger** — globally excluded from inputs (v24); it's vx's own metadata, never a task input                                                                                             |
-| Change a file in a nested project's dir                                                                                                  | **NOT a trigger** for the parent's `files` globs — project boundaries are hard (workspaceFiles is the explicit exception)                                                                       |
-
-The cascade in step 10 is what makes monorepo caching work: edit a
+| Trigger                                                                                                                                  | Mechanism                                                                                                                                                                                               |
+| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Edit a file in the task's `inputs.files` set                                                                                             | step 10 of key derivation                                                                                                                                                                               |
+| Edit a file in the task's `inputs.workspaceFiles` set (root-anchored; may live in ANY project's dir — the documented boundary exception) | step 10 — resolved workspace files join the same input-file list                                                                                                                                        |
+| Any package manager updates a lockfile (`pnpm`, `npm`, `yarn`, `bun`)                                                                    | step 9 — the `key` material of the plugin that claims it (`@vzn/vx-lockfile`: only the projects whose dependency closure moved); **NOT a trigger** with no such plugin, since core keys no package file |
+| Edit an install setting (`.npmrc`, `bunfig.toml`, `pnpm-workspace.yaml`, `.yarnrc.yml`)                                                  | step 9 — the claiming lockfile plugin folds it whole into every task; **NOT a trigger** without one                                                                                                     |
+| Edit `package.json`'s `workspaces` field                                                                                                 | membership: a project that joins or leaves changes which projects exist and which nested dirs its parent's globs exclude (step 10)                                                                      |
+| Edit the project's `package.json` (dep / version / scripts change)                                                                       | step 10 — an input file of every cached task when `@vzn/vx-lockfile` is declared (it adds `package.json` to `cache.inputs.files`), or when a task lists it; **NOT a trigger** otherwise                 |
+| Edit the task's `vx.config.ts`                                                                                                           | step 3 (task config hash)                                                                                                                                                                               |
+| Edit a config file that the task config imports                                                                                          | step 3 (configHash sees the resolved object after Bun evaluates imports)                                                                                                                                |
+| Change CLI `forwardArgs` (after `--`)                                                                                                    | step 4                                                                                                                                                                                                  |
+| Change a `cache.inputs.env` host value                                                                                                   | step 5                                                                                                                                                                                                  |
+| Change the combined stdout+stderr of a `cache.inputs.runtime` command (resolved at hash time)                                            | step 6                                                                                                                                                                                                  |
+| Change the combined stdout+stderr of a `cache.inputs.workspaceRuntime` command (resolved at hash time)                                   | step 7                                                                                                                                                                                                  |
+| Upstream task's cache key changes (because its inputs changed)                                                                           | step 8                                                                                                                                                                                                  |
+| Bump `CACHE_VERSION`                                                                                                                     | step 1 — orphans every entry                                                                                                                                                                            |
+| Change `exec.env.passThrough` _values_ alone                                                                                             | **NOT a trigger** by design — passThrough values are host-specific                                                                                                                                      |
+| Change a file not in `inputs.files` / `inputs.workspaceFiles`                                                                            | **NOT a trigger** by design — declare it explicitly                                                                                                                                                     |
+| Edit `.vx/projects.lock.json`                                                                                                            | **NOT a trigger** — globally excluded from inputs (v24); it's vx's own metadata, never a task input                                                                                                     |
+| Change a file in a nested project's dir                                                                                                  | **NOT a trigger** for the parent's `files` globs — project boundaries are hard (workspaceFiles is the explicit exception)                                                                               |
+
+The cascade in step 8 is what makes monorepo caching work: edit a
 file in `lib/`, and every package that depends on `lib`'s `build` task
 re-runs automatically.
 
@@ -934,7 +951,7 @@ them (X-57). The same set fences the output clean, so a root
 glob pass drops a path under one of them (an ancestor lookup,
 A-11). The only way
 for project A to depend on project B's state via project-relative
-globs is `dependsOn` + upstream-hash propagation (step 10).
+globs is `dependsOn` + upstream-hash propagation (step 8).
 
 For a task with `exec.sandbox` and `cache`, the sandbox enforces that
 "only". A workspace package reached through a `node_modules` link is
@@ -1020,7 +1037,7 @@ exactly on `cache.inputs.env`, and they share its asymmetry with the
 lockfile:
 
 - **The command _strings_ live in the resolved config**, so `vx lock`
-  freezes them into `vx-lock.json` (just as it freezes the env _names_
+  freezes them into `.vx/projects.lock.json` (just as it freezes the env _names_
   a task declares).
 - **The command _output_ is resolved live at hash time on every run**
   — inside `resolveInputs`, the same place env _values_ are read from
@@ -1052,10 +1069,10 @@ A probe runs in its own process group. One still running when vx exits
 SIGKILLed with its whole tree; until 2026-09-27 (A-9) it ran on under
 init. A `kill -9` of vx runs no exit hook, and leaves it.
 
-So `vx run --frozen` loads the frozen command strings but still spawns
-them and folds their current output into the key. A `node -v` that goes
-from `v20` to `v22` after the lock was written busts the cache under
-`--frozen`, exactly as a changed `NODE_ENV` value would — the TypeScript
+So a run loads the frozen command strings from the lock but still
+spawns them and folds their current output into the key. A `node -v`
+that goes from `v20` to `v22` after the lock was written busts the
+cache, exactly as a changed `NODE_ENV` value would — the TypeScript
 escape hatch (`define: { TSC_VERSION: execSync(...) }`) goes stale here
 because its value was baked into the config object at lock time, whereas
 a runtime input re-resolves.
@@ -1107,7 +1124,7 @@ has staged). Machines sharing a workspace over a network file system
 do not share a temp directory, so they do not share the lock.
 
 An eviction can still land between a hit's probe and its restore: a
-`vx cache prune` in another shell, or the `cacheRetention` of another
+`vx cache clean` in another shell, or the `cache.retention` of another
 workspace that shares the `--cache-dir` (a different workspace, so a
 different lock), which cannot see this run's pending `accessed_at`
 bumps and reads its fresh hits as old. The restore then finds no
@@ -1132,16 +1149,15 @@ only read keeps the entry (`…; left it (this cache is read-only)`).
 
 The run must be able to write here — it records its history at the
 end of every run, hit or miss — so a directory this user cannot write
-into (another user's `.vx`, a read-only checkout) fails the run before
+into (another user's `.vx/cache`, a read-only checkout) fails the run before
 any task: `cache directory <path> is not writable (EACCES: …)`, with
-`--cache-dir <path>` as the way out. `vx cache prune` is refused the
+`--cache-dir <path>` as the way out. `vx cache clean` is refused the
 same way (its `--dry-run` only reads, and reads). The readers (`vx show`, `why`,
-`last`, `info`) open such a directory read-only and go on: a config
-that misses the evaluation cache is evaluated live and not stored.
+`last`, `info`) open such a directory read-only and go on.
 Where the directory cannot be created at all (a read-only checkout with
 no cache yet) a run says `cannot create cache directory <path>
-(EACCES: …)`, naming the workspace `cacheDir` field and `--cache-dir`;
-the readers and `vx cache prune` find no cache and go on.
+(EACCES: …)`, naming the workspace `cache.dir` field and `--cache-dir`;
+the readers and `vx cache clean` find no cache and go on.
 A full disk is the same kind of failure and is reported the same way,
 never as a corrupt artifact and never as a stack: a save that runs out
 of room is `[vx] cache save failed: ENOSPC …` (the task's work ran, the
@@ -1175,6 +1191,8 @@ By default the entries and their artifacts live in a **shared store**
 in `~/.vx/<id>/cache`, and each workspace keeps only its own index in
 its `.vx/cache`: every checkout of the repository hits what another
 saved (a second clone, a worktree), and none reads another's history.
+Task timings are shared too: `task_durations`, what a duration forecast
+reads, so a new worktree has one on its first run.
 The id is Nx 23's: 16 hex of a sha256 of the remote (`origin`, then
 `upstream`, `base`, the first; `host/owner/repo` in lower case, so ssh
 and https agree) and the workspace's path in the repository; with no
@@ -1185,7 +1203,8 @@ owner-only; vx closes one of yours that others can read (chmod 700), and one oth
 ```
 ~/.vx/<id>/cache/                           the shared store
 ├── store.db                                entries, entry_stdout, output_files,
-│                                           entry_inputs, store_meta; artifacts
+│                                           entry_inputs, task_durations,
+│                                           store_meta; artifacts
 │                                           of at most 32 KiB compressed (v33)
 └── <hash>.tar.zst                          the larger artifacts (below)
 
@@ -1204,7 +1223,7 @@ when its task next hits. The check, drop, re-create and stamp are one
 write transaction, so another version's open waits rather than landing
 between them. A home this user cannot write keeps the store
 in `<workspaceRoot>/.vx/cache/` instead, silently. Name a
-cache directory (`cacheDir` in vx.workspace.ts, `--cache-dir`, or
+cache directory (`cache.dir` in .vx/workspace.ts, `--cache-dir`, or
 `VX_CACHE_DIR`, in that order of precedence, relative to the workspace
 root) and it holds everything, shared with no other workspace:
 
@@ -1404,7 +1423,7 @@ miss, and the save that follows replaces it. An inline artifact with no
 row is indexed the same way, from its bytes, in one transaction; a reset
 keeps the `artifacts` table, but deleting `store.db` or `cache.db` by
 hand takes the inline artifacts with it. A `.tmp-*` a crashed save
-left is never a hit. `vx cache prune` sweeps row-less files, and so does a run whose workspace declares `cacheRetention`, at
+left is never a hit. `vx cache clean` sweeps row-less files, and so does a run whose workspace declares `cache.retention`, at
 most once an hour (the sweep's clock is `schema_meta.orphans_swept_at`;
 the policy sums index rows, so orphans alone never make it due). A
 row-less artifact may be in use: two vx versions share one store, and
@@ -1437,39 +1456,29 @@ hit replays it with pure SQL, never decompressing the artifact).
 `SCHEMA_VERSION`, earlier or newer, is reset by the first run that opens
 it (pre-alpha: no migrations; the index is an inventory, owner
 2026-10-06): every table but `schema_meta` is dropped and recreated,
-so each comes back in its current shape (A-54: `config_closures` and
-`output_dirs` kept an earlier vx's columns). The check, drop, re-create
+so each comes back in its current shape (A-54: `output_dirs` kept an
+earlier vx's columns). The check, drop, re-create
 and stamp are one write transaction, so another version's open waits
 rather than landing between them; an index already current is opened
 without the lock.
 A reading verb (`vx why`, `vx last`, `vx info`) leaves it untouched and
-says why (item 896; `vx cache prune --dry-run` previews the reset
+says why (item 896; `vx cache clean --dry-run` previews the reset
 instead, item 1083).
 That open prints nothing (owner, 2026-10-06: the cache is vx's to
 keep). The artifacts stay: each is indexed again from its own bytes
 when its task next asks for its key (below).
 
 ```sql
--- src/cache/schema.ts (SCHEMA_VERSION = 'v34', in cache.ts)
--- With a shared store, entries, entry_stdout, output_files, entry_inputs
--- and store_meta live in its store.db, attached as `store`; the rest is
+-- src/cache/schema.ts (SCHEMA_VERSION = 'v36', in cache.ts)
+-- With a shared store, entries, entry_stdout, output_files, entry_inputs,
+-- store_meta and task_durations live in its store.db, attached as `store`; the rest is
 -- the workspace's cache.db. A named cache dir holds all of them.
 
 CREATE TABLE schema_meta (
-  key   TEXT PRIMARY KEY,  -- 'version', 'cache_version', 'orphans_swept_at', 'file_hashes_swept_at', 'config_evals_swept_at', 'store_dir'
+  key   TEXT PRIMARY KEY,  -- 'version', 'cache_version', 'orphans_swept_at', 'file_hashes_swept_at', 'store_dir'
   value TEXT NOT NULL
 );
 
--- The config-evaluation cache (§ Config evaluation cache): the validated,
--- JSON-serialised result of a provably pure config, keyed by everything
--- the evaluation could have observed. Machine-local. Rows not written in
--- 30 days are swept at most once a day (`config_evals_swept_at`).
-CREATE TABLE config_evals (
-  key        TEXT PRIMARY KEY,
-  json       TEXT NOT NULL,
-  created_at INTEGER NOT NULL
-);
-
 CREATE TABLE entries (
   hash         TEXT PRIMARY KEY,  -- the 16-hex xxh3 cache key
   project      TEXT NOT NULL,
@@ -1550,7 +1559,7 @@ CREATE INDEX runs_failed ON runs(hash) WHERE status = 'failed';
 
 -- The file-hash memo: a content hash per input file that git could not
 -- answer (untracked or dirty), keyed by the stat identity that proves
--- the bytes unchanged. Machine-local; § Cache key derivation step 12.
+-- the bytes unchanged. Machine-local; § Cache key derivation step 10.
 -- A writing close drops rows unwritten for 30 days, at most once a day
 -- (a memo miss is the whole cost of a dropped row; item 1082).
 CREATE TABLE file_hashes (
@@ -1608,15 +1617,6 @@ CREATE TABLE output_stamps (
   PRIMARY KEY (entry_hash, path)
 );
 
--- Each config's ORDERED import closure (the config first), so a warm
--- load keys it by stat-hashing the list through file_hashes instead of
--- reading every file. Machine-local; pruned with config_evals.
-CREATE TABLE config_closures (
-  config_path TEXT PRIMARY KEY,
-  files_json  TEXT NOT NULL,
-  created_at  INTEGER NOT NULL
-);
-
 -- Every directory under a whole-subtree output glob, with its mtime as
 -- of the last save or restore on THIS machine: unchanged mtimes prove
 -- the output SET unchanged without a glob walk. Machine-local — a remote
@@ -1693,6 +1693,20 @@ CREATE TABLE store_meta (
   value TEXT NOT NULL
 );
 
+-- v36: each executed success's duration, appended in the run's history
+-- transaction, in the store so every worktree forecasts from it.
+-- source: 'branch:<name>'; the forecast reads the newest five per task.
+CREATE TABLE task_durations (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  project     TEXT NOT NULL,
+  task        TEXT NOT NULL,
+  source      TEXT NOT NULL,
+  sha         TEXT,
+  duration_ms INTEGER NOT NULL,
+  recorded_at INTEGER NOT NULL
+);
+CREATE INDEX task_durations_task ON task_durations(project, task, source, id);
+
 -- v33: an artifact of at most 32 KiB compressed, its exact <hash>.tar.zst
 -- bytes, written in the transaction that writes its entry rows. In the
 -- store (or a named cache dir's cache.db), and outside every drop a
@@ -1749,28 +1763,6 @@ moat.
 - **One handle, one schema-meta sentinel.** An older schema drops
   and recreates every table but `schema_meta` (pre-alpha) — there's no migration code to maintain.
 
-## Config evaluation cache
-
-Evaluating configs is the largest fixed cost of a warm run on a big
-workspace (~80 ms for 1000 synthetic configs; reading them as data is
-~12 ms). A config that is **provably pure** — every import relative or
-`@vzn/vx`, and no mention of `process`, `Bun`, `Date`, `fetch`,
-`import.meta`, `require`, a dynamic `import()`, `await`, … outside string
-literals and comments — is served from `cache.db`'s `config_evals` table,
-keyed by the git blob id of the config and of every file in its
-relative import closure, the workspace fingerprint (lockfiles) and Bun's
-version. Editing a shared preset moves the key. On a warm run the
-closure is remembered per config, so the key comes from a stat-backed
-identity per file — no read, no scan — for every config whose relative
-imports name their files outright: an explicit extension, the file
-itself, no symlink on the way (an extensionless import, a `.js` Bun
-answers with a `.ts`, or a link could be re-resolved without touching a
-listed file, so such a config keeps the scan). Anything the static check cannot prove
-pure evaluates live, exactly as before, so the cache can be slower but
-not wrong for a config written in good faith (the check is syntactic; one
-built to defeat it can). Details and the deny-list:
-[`modules/config-cache.md`](./modules/config-cache.md).
-
 ## Performance characteristics
 
 - **Hashing cost** on a clean tree is near-zero per file: git index
@@ -1789,15 +1781,16 @@ built to defeat it can). Details and the deny-list:
   transaction, which holds a small artifact's bytes itself; a large one
   adds a temp write and an atomic rename. Hashing dominates the run; storage itself
   is cheap. The remote upload (if any) is backgrounded.
-- **Workspace fingerprint** is computed once per `vx run` invocation
-  and reused for every task in that run; after a task that may rewrite
-  one of its files ran, one `stat` per file re-checks it (item 750).
+- **Claimed root files** (a lockfile plugin's lockfile and settings)
+  are read once per `vx run` invocation; after a task that may rewrite
+  one ran, one `stat` per file re-checks it (item 750). With no plugin
+  claiming one, nothing is read.
 
 ## What's NOT in the key (and why)
 
 - **`exec.env.passThrough` _values_.** Would force cache misses across
   machines with different CI flags, regions, or shell prompts. The
-  _names_ are in the config hash (step 5) so adding/removing a
+  _names_ are in the config hash (step 3) so adding/removing a
   passthrough still bumps the key for affected tasks.
 - **Files outside the project directory that aren't declared.**
   Workspace-root configs (`tsconfig.base.json`, etc.) are not
@@ -1807,11 +1800,13 @@ built to defeat it can). Details and the deny-list:
   The canonical mechanism is `cache.inputs.runtime` /
   `workspaceRuntime` (e.g. `workspaceRuntime: ['node -v']`): the
   command output is resolved live at hash time, so it stays correct
-  under `--frozen`. Avoid baking versions via
+  under the lock. Avoid baking versions via
   `define: { X: execSync(...) }` — that value freezes into the config
   object at lock time and goes stale.
-- **`vx-lock.json`** — globally excluded (v24); also filtered out of
-  `--affected` change sets.
+- **`.vx/projects.lock.json`** — globally excluded (v24); also filtered out of
+  `--affected` change sets. So are the files `vx lock` and `vx init`
+  write beside it: each project's `vx.lock.json` review copy,
+  `.vx/.gitattributes` and `.vx/.gitignore`.
 - **`exec.remote`.** Pure PLACEMENT: it decides _where_ a task runs,
   never what it produces, so pinning a task to this machine does not
   bust its cache. It must not — the
@@ -1833,8 +1828,8 @@ The cache records the version it was written under
 (`schema_meta.cache_version`). After an upgrade every cached task
 misses once and re-saves, with nothing printed (owner, 2026-10-06: the
 cache is vx's to keep). The index survives, so the old entries stay
-until they age out under `vx cache prune --older-than` or
-`cacheRetention`; no key derives to them again.
+until they age out under `vx cache clean --older-than` or
+`cache.retention`; no key derives to them again.
 
 Required when:
 
@@ -1854,6 +1849,9 @@ Not required when:
   background uploads) — key derivation and artifact bytes untouched.
 - Doc-only updates.
 - Refactors that don't change the bytes fed into the hash.
+- A key part leaves the chain: every key moves, so no unchanged key
+  holds wrong bytes (`v43` stayed when core stopped folding the
+  `workspace:` and `pkg:` parts, 2026-10-14).
 
 `tests/contract-stored-format.test.ts` holds the layout rows: it
 records the index's DDL beside `SCHEMA_VERSION` and a fixture
@@ -1878,6 +1876,14 @@ breaking footer).
 
 ### History
 
+- **v43 kept** (2026-10-14): core stopped folding the project's
+  `package.json` and the root fingerprint files; every key moved, so
+  nothing replays wrong bytes and no bump was needed.
+- **v42 → v43**: stored bytes wrong under an unchanged key (Security
+  F4, 2026-10-14). A scoped run stored its local entries under the
+  default key, so a later default run on the same disk replayed a PR's
+  bytes. A scoped run now stores under the scope's key locally as it
+  does remotely; the fix cannot reach an entry already saved that way.
 - **v41 → v42**: the stored output became both streams in the order
   the run printed them (`orchestrator/output-log.ts`), so a hit replays
   stderr too. A v41 entry holds stdout alone.
@@ -2076,7 +2082,7 @@ breaking footer).
   artifact is gone or cannot produce an output the index recorded (the
   caller has already wiped the declared outputs by then, so a quiet
   return reported a green hit over an emptied tree — reachable via a
-  concurrent `vx cache prune`); the tar reader rejects an entry whose
+  concurrent `vx cache clean`); the tar reader rejects an entry whose
   declared size runs past the end of the archive (`subarray` clamps, so
   it used to install short, NUL-padded content as a cache hit instead of
   degrading to a miss); and directory entries now get the same
@@ -2120,7 +2126,7 @@ breaking footer).
   so existing artifacts stay valid and `CACHE_VERSION` stays `v24`. The
   schema gate drops + recreates on the version mismatch (pre-alpha, no
   migration).
-- **v23 → v24**: exclude `vx-lock.json` from the input file set
+- **v23 → v24**: exclude `.vx/projects.lock.json` from the input file set
   globally (`ALWAYS_IGNORE` in `cache/inputs.ts`). The lockfile is
   committed, so git enumerates it, but it's vx's own frozen-config
   metadata — never a task input. Without this, a `vx lock` re-write
@@ -2131,7 +2137,7 @@ breaking footer).
 
 - **v22 → v23**: fold `cache.inputs.runtime` / `workspaceRuntime`
   command output into the key (two namespaced sections after
-  env-values). The command _strings_ stay in the config hash (step 5);
+  env-values). The command _strings_ stay in the config hash (step 3);
   their combined trimmed stdout+stderr is resolved live at hash time
   and folded as `runtime-values:` (project-cwd) and `ws-runtime-values:`
   (root-cwd) sections, each `command\0output`. No SCHEMA bump — only
@@ -2164,7 +2170,7 @@ breaking footer).
 - **v9 → v10** (PR #7): on-disk layout switched from per-entry
   `meta.json` + `outputs/` directory to a workspace-wide `cache.db`
   (SQLite) plus output files directly at `<hash>/` and log files at
-  `logs/<hash>.{stdout,stderr}`. Adds run history for `vx stats`.
+  `logs/<hash>.{stdout,stderr}`. Adds run history for `vx info`.
   Removes the per-entry manifest.
 - **v10 → v11** (PR #19): analytics columns added to the `runs`
   table: `run_id` (UUIDv7), `cpu_ms`, `peak_rss_bytes`,
@@ -2234,7 +2240,7 @@ breaking footer).
   transitive-deps to nearest-holder frontier semantics (Turbo/Nx
   direct-deps parity, plus vx's sparse bridging through deps that
   don't declare the task). Task graphs lose the redundant deep edges,
-  so the filtered-upstream-hash set (step 10) shrinks for any task
+  so the filtered-upstream-hash set (step 8) shrinks for any task
   whose deps chain `'^task'` themselves — same inputs now derive a
   different key. Reachability/ordering is unchanged whenever holders
   chain `'^task'` (the universal pattern); a holder that doesn't is