@vzn/vx 0.0.635 → 0.0.637

package/docs/patterns.md

@@ -27,24 +27,25 @@ restore. Everything else lines up with Turbo or Nx by design.
 
 ### Cache key composition
 
-The set of bytes fed into the hash mirrors Turbo's key recipe with one
-Nx-borrowed extension.
-
-| Component                              | Turbo        | Nx                     | vx         | vx source                                     |
-| -------------------------------------- | ------------ | ---------------------- | ---------- | --------------------------------------------- |
-| Task identity (`project#task`)         | yes          | yes                    | yes        | `src/cache/layer.ts` (`CacheKeyInput.taskId`) |
-| Resolved command + env declarations    | yes          | yes                    | yes        | `src/cache/layer.ts` (`taskConfigHash`)       |
-| Declared input file contents           | yes          | yes                    | yes        | `src/cache/layer.ts` (`inputFiles`)           |
-| Declared env-var **values** at runtime | yes          | yes                    | yes        | `src/cache/layer.ts` (`envValues`)            |
-| Upstream task hashes (cascade)         | yes          | yes                    | yes        | `src/cache/layer.ts` (`upstreamHashes`)       |
-| Workspace lockfile fingerprint         | yes          | yes                    | yes        | `src/cache/layer.ts` (`workspaceFingerprint`) |
-| Forwarded CLI args (after `--`)        | yes          | yes                    | yes        | `src/cache/layer.ts` (`forwardArgs`)          |
-| Project `package.json` bytes (direct)  | via lockfile | `externalDependencies` | **direct** | `src/cache/layer.ts` ("Turbo / Nx parity")    |
-
-The `package.json` fold is the Nx-borrowed move (Turbo gets it
-transitively through the lockfile; Nx's `externalDependencies` does it
-explicitly). We fold the bytes directly so narrow `cache.inputs.files`
-like `['src/**']` doesn't miss a `package.json` dep bump.
+The set of bytes fed into the hash mirrors Turbo's key recipe; the
+package-manager parts come from a plugin.
+
+| Component                              | Turbo        | Nx                     | vx     | vx source                                     |
+| -------------------------------------- | ------------ | ---------------------- | ------ | --------------------------------------------- |
+| Task identity (`project#task`)         | yes          | yes                    | yes    | `src/cache/layer.ts` (`CacheKeyInput.taskId`) |
+| Resolved command + env declarations    | yes          | yes                    | yes    | `src/cache/layer.ts` (`taskConfigHash`)       |
+| Declared input file contents           | yes          | yes                    | yes    | `src/cache/layer.ts` (`inputFiles`)           |
+| Declared env-var **values** at runtime | yes          | yes                    | yes    | `src/cache/layer.ts` (`envValues`)            |
+| Upstream task hashes (cascade)         | yes          | yes                    | yes    | `src/cache/layer.ts` (`upstreamHashes`)       |
+| Workspace lockfile                     | yes          | yes                    | plugin | `@vzn/vx-lockfile` (`VxPlugin.fingerprint`)   |
+| Forwarded CLI args (after `--`)        | yes          | yes                    | yes    | `src/cache/layer.ts` (`forwardArgs`)          |
+| Project `package.json` bytes           | via lockfile | `externalDependencies` | plugin | `@vzn/vx-lockfile` (an input file)            |
+
+Core keys no package file (2026-10-14): the lockfile and each
+project's `package.json` key a task through `@vzn/vx-lockfile`, which
+claims the lockfile and adds `package.json` to every cached task's
+inputs, so narrow `cache.inputs.files` like `['src/**']` doesn't miss a
+`package.json` dep bump.
 
 The two **divergences** from Turbo's recipe — TypeScript-resolved
 config hash and per-task forwarded-args fold — are documented in
@@ -91,12 +92,12 @@ parser's docblock marks them (`src/graph/dependency-spec.ts`).
 
 ### Workspace discovery
 
-| Capability                                            | Source       | vx source                        |
-| ----------------------------------------------------- | ------------ | -------------------------------- |
-| Read `pnpm-workspace.yaml`                            | pnpm + Turbo | `src/workspace/workspace.ts`     |
-| Read `package.json` `workspaces` (npm/yarn/bun)       | Turbo        | `src/workspace/workspace.ts`     |
-| Build package-dep graph from workspace `dependencies` | Turbo + Nx   | `src/workspace/package-graph.ts` |
-| Lockfile fingerprint at workspace level               | Turbo + Nx   | `src/workspace/fingerprint.ts`   |
+| Capability                                            | Source       | vx source                         |
+| ----------------------------------------------------- | ------------ | --------------------------------- |
+| Read `pnpm-workspace.yaml` (adoption)                 | pnpm + Turbo | `@vzn/vx-migrate`'s `packages.ts` |
+| Read `package.json` `workspaces` (adoption)           | Turbo        | `@vzn/vx-migrate`'s `packages.ts` |
+| Build package-dep graph from workspace `dependencies` | Turbo + Nx   | `src/workspace/package-graph.ts`  |
+| Lockfile fingerprint at workspace level               | Turbo + Nx   | `src/workspace/fingerprint.ts`    |
 
 ### Cache topology
 
@@ -140,7 +141,7 @@ Turbo-aware cache server can transit our blobs unchanged.
 | Independent siblings continue past failure                    | Turbo `--continue=dependencies-successful`         | `src/graph/scheduler.ts`                                                    |
 | Persistent / long-running tasks (dev servers)                 | Turbo `persistent`, Nx `continuous`                | `src/exec/runner.ts` (`runPersistent`) + `src/orchestrator/execute-task.ts` |
 | Project-local `node_modules/.bin` on PATH                     | Turbo + pnpm                                       | `src/exec/env.ts` (`binPaths`)                                              |
-| Implicit project-`package.json` invalidation                  | Turbo (via lockfile) + Nx (`externalDependencies`) | `src/orchestrator/task-hash.ts` ("Matches Turbo and Nx")                    |
+| Project-`package.json` invalidation, by a plugin              | Turbo (via lockfile) + Nx (`externalDependencies`) | `@vzn/vx-lockfile` (its `project` stage lists it as an input)               |
 
 ### Output handling
 
@@ -183,17 +184,15 @@ Sharing the patterns doesn't mean sharing the overhead. On the
 476-package / 1,428-node synthetic workspace
 (`packages/vx-bench/compare.ts 20 25 1`, 2026-09-02):
 
-| Runner | Warm (no restore)       | Warm (restore)          |
-| ------ | ----------------------- | ----------------------- |
-| **vx** | **297 ms**              | **416 ms**              |
-| Turbo  | 342 ms (vx 15% faster)  | 612 ms (vx 47% faster)  |
-| Nx     | 1.38 s (vx 4.6× faster) | 1.33 s (vx 3.2× faster) |
+| Runner | Warm (no restore) | Warm (restore) |
+| ------ | ----------------- | -------------- |
+| **vx** | **297 ms**        | **416 ms**     |
+| Turbo  | 342 ms            | 612 ms         |
+| Nx     | 1.38 s            | 1.33 s         |
 
 A cached run is all runner overhead. Cold builds are compared by the
 time the runner adds, on [`benchmarks.md`](./benchmarks.md).
 
-vx N% faster: that tool takes N% longer than vx; N× faster: N times as long.
-
 Full breakdown + methodology in [`benchmarks.md`](./benchmarks.md).
 
 ## Where the lineage diverges