@convesoft/nx-rust 1.0.0-rc.1 → 1.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/PLUGIN.md +106 -0
  2. package/README.md +8 -4
  3. package/docs/artifacts.mara.md +374 -0
  4. package/docs/caching.mara.md +999 -0
  5. package/docs/ci.mara.md +308 -0
  6. package/docs/configuration.mara.md +508 -0
  7. package/docs/decisions.mara.md +3267 -0
  8. package/docs/execution.mara.md +533 -0
  9. package/docs/index.mara.md +51 -0
  10. package/docs/product.mara.md +366 -0
  11. package/docs/release.mara.md +493 -0
  12. package/docs/setup.mara.md +486 -0
  13. package/docs/targets.mara.md +704 -0
  14. package/docs/testing.mara.md +431 -0
  15. package/docs/verification.mara.md +465 -0
  16. package/docs/workspaces.mara.md +445 -0
  17. package/package.json +1 -1
  18. package/src/cargo/build-settings.d.ts +8 -1
  19. package/src/cargo/build-settings.js +21 -11
  20. package/src/cargo/build-settings.js.map +1 -1
  21. package/src/cargo/metadata.d.ts +2 -0
  22. package/src/cargo/metadata.js.map +1 -1
  23. package/src/cargo/redirections.d.ts +4 -1
  24. package/src/cargo/redirections.js +7 -2
  25. package/src/cargo/redirections.js.map +1 -1
  26. package/src/cargo/warnings-setting.d.ts +24 -0
  27. package/src/cargo/warnings-setting.js +81 -0
  28. package/src/cargo/warnings-setting.js.map +1 -0
  29. package/src/executors/cargo/schema.json +4 -0
  30. package/src/executors/cargo-output.d.ts +8 -2
  31. package/src/executors/cargo-output.js +20 -6
  32. package/src/executors/cargo-output.js.map +1 -1
  33. package/src/executors/command.d.ts +13 -0
  34. package/src/executors/command.js +37 -7
  35. package/src/executors/command.js.map +1 -1
  36. package/src/executors/denied-warnings.d.ts +99 -0
  37. package/src/executors/denied-warnings.js +188 -0
  38. package/src/executors/denied-warnings.js.map +1 -0
  39. package/src/executors/group-run.d.ts +1 -1
  40. package/src/executors/group-run.js +23 -13
  41. package/src/executors/group-run.js.map +1 -1
  42. package/src/executors/groups.d.ts +7 -2
  43. package/src/executors/groups.js +22 -3
  44. package/src/executors/groups.js.map +1 -1
  45. package/src/executors/nextest.d.ts +6 -2
  46. package/src/executors/nextest.js +12 -6
  47. package/src/executors/nextest.js.map +1 -1
  48. package/src/executors/task-guards.js +7 -2
  49. package/src/executors/task-guards.js.map +1 -1
  50. package/src/executors/task.js +10 -3
  51. package/src/executors/task.js.map +1 -1
  52. package/src/executors/test-mode.d.ts +4 -1
  53. package/src/executors/test-mode.js +7 -1
  54. package/src/executors/test-mode.js.map +1 -1
  55. package/src/executors/test-steps.d.ts +20 -8
  56. package/src/executors/test-steps.js +45 -14
  57. package/src/executors/test-steps.js.map +1 -1
  58. package/src/graph/caching.js +5 -0
  59. package/src/graph/caching.js.map +1 -1
  60. package/src/graph/clippy-input.d.ts +53 -0
  61. package/src/graph/clippy-input.js +107 -0
  62. package/src/graph/clippy-input.js.map +1 -0
  63. package/src/graph/collisions.d.ts +7 -0
  64. package/src/graph/collisions.js.map +1 -1
  65. package/src/graph/discovery.d.ts +15 -0
  66. package/src/graph/discovery.js +5 -0
  67. package/src/graph/discovery.js.map +1 -1
  68. package/src/graph/inputs.d.ts +3 -1
  69. package/src/graph/inputs.js +11 -1
  70. package/src/graph/inputs.js.map +1 -1
  71. package/src/graph/projects.js +13 -2
  72. package/src/graph/projects.js.map +1 -1
  73. package/src/graph/rustfmt-config.d.ts +42 -0
  74. package/src/graph/rustfmt-config.js +173 -0
  75. package/src/graph/rustfmt-config.js.map +1 -0
  76. package/src/graph/targets.d.ts +11 -7
  77. package/src/graph/targets.js +12 -8
  78. package/src/graph/targets.js.map +1 -1
@@ -0,0 +1,3267 @@
1
+ # Decisions and risks
2
+
3
+ The choices behind nx-rust, the risks it carries, and the evidence the choices
4
+ rest on. Most of this comes from a design discussion recorded on 12 November 2026.
5
+
6
+ ## Decisions
7
+
8
+ :::mara decision ADR-NEW-PLUGIN
9
+ :mid: 01M78FHG7FZFXQ6B84EG2CKHRS
10
+ :title: Build a new plugin that closes the gaps of the existing ones
11
+ :status: accepted
12
+ :justifies: REQ-DEPENDENCY-EDGES
13
+ :justifies: REQ-EXTERNAL-DEPS
14
+ :justifies: REQ-MULTI-WORKSPACE
15
+ :justifies: REQ-BATCHING
16
+
17
+ Three projects were read before this design. [eddacraft/nxrust](https://github.com/eddacraft/nxrust) (v0.3.0) is the closest prior art and already reads overrides from Cargo metadata. [@monodon/rust](https://github.com/Cammisuli/monodon) (3.0.0, requires Nx 22) is the plugin the Nx documentation lists, and the reference for Nx release on `Cargo.toml`. [max-sixty/cargo-affected](https://github.com/max-sixty/cargo-affected) (0.4.1, self-described as very early) selects tests by coverage on top of nextest.
18
+
19
+ None of them is a dependency of this design, except cargo-affected, which is optional. nx-rust is a separate plugin whose design starts from the gaps found in nxrust ([[EVD-NXRUST-GAPS]]): dev-dependencies missing from the graph, the whole lockfile as an input, no batching and no handling of feature unification, unhashed build-script and Cargo configuration inputs, an in-memory metadata cache with the workspace fixed at the Nx root, and builds that restore `rlib` files into Cargo's directory.
20
+ :::
21
+
22
+ :::mara decision ADR-CARGO-SOURCE-OF-TRUTH
23
+ :mid: 01M78FHG7F2CB9W8YBQ9DNXCB0
24
+ :title: Take projects, targets and dependencies from cargo metadata
25
+ :status: accepted
26
+ :justifies: REQ-INFERRED-PROJECTS
27
+ :justifies: DES-METADATA-REPORT
28
+ :justifies: DES-DISCOVERY
29
+
30
+ A second description of a crate, such as a `project.json`, has to be written, kept in step with `Cargo.toml` and reviewed, and it drifts. Cargo already knows the members, their targets and their dependencies, and reports them through `cargo metadata`. The plugin takes everything from that report and needs no per-crate Nx file. The cost is one cargo call per workspace when the graph is created, and a design that is limited to what Cargo reports plus the metadata tables.
31
+
32
+ It also means that every machine that computes the graph needs cargo, including one that only runs JS tasks. When cargo is missing or rejects a manifest, graph creation fails. Leaving the Rust projects out instead was rejected: that machine would have another graph and other cache keys than the rest of the team, and `nx affected` would skip crates without saying so.
33
+ :::
34
+
35
+ :::mara decision ADR-METADATA-NO-DEPS
36
+ :mid: 01M78RC7T7GK1RSH8S11ZV38EZ
37
+ :title: Build the graph from cargo metadata without dependency resolution
38
+ :status: accepted
39
+ :justifies: DES-METADATA-REPORT
40
+
41
+ `cargo metadata` can resolve the whole dependency graph or, with `--no-deps`, report only the workspace's own packages. The full report was the first assumption. It needs the manifest of every dependency, so on a machine without a filled Cargo cache it downloads the crates of the lockfile, and it creates or updates `Cargo.lock` on the way. Nx builds the project graph for every command, also for JS-only work and in every CI job, and each of those machines needs cargo ([[ADR-CARGO-SOURCE-OF-TRUTH]]). The full report would add a registry download to all of them.
42
+
43
+ The plugin therefore asks with `--no-deps`. That report still names the members, their targets, their declared dependencies with paths and features, the metadata tables and Cargo's directories, which is all that projects, targets and edges need, apart from the crates that `[patch]`, `[replace]` and `paths` redirect to ([[EVD-CARGO-NO-DEPS]]). What it lacks is the resolved versions of external crates. Only per-crate lockfile hashing needs those, and `Cargo.lock` holds them. The cost is that the plugin reads `Cargo.lock` itself for that purpose, that a path dependency outside the workspace needs a report of its own, and that the plugin reads the redirection tables from Cargo's manifests and configuration files itself ([[ADR-REDIRECTION-EDGES]]).
44
+ :::
45
+
46
+ :::mara decision ADR-NO-METADATA-CACHE
47
+ :mid: 01M7AY77VPMGWNN9SVRD56JAPH
48
+ :title: Request the cargo metadata report afresh in every graph computation
49
+ :status: accepted
50
+ :justifies: DES-METADATA-REPORT
51
+
52
+ Agreed with the maintainer on 13 November 2026. [[REQ-METADATA-DISK-CACHE]] planned to keep a workspace's `cargo metadata` report between Nx processes. With `--no-deps` ([[ADR-METADATA-NO-DEPS]]) the report is cheap: 180 ms for the 598 members of polkadot-sdk, the largest workspace measured, 79 ms for 262 members and 13 ms for 55, against about 15 to 30 ms to read a stored report back and check it ([[EVD-METADATA-TIMING]]). The runs that would gain most are those without the Nx daemon, as in CI, where the first command of a job finds nothing stored.
53
+
54
+ A stored report could be reused only under a key that covers everything the report depends on: which target files and READMEs exist, gitignored ones included, which Nx's file map leaves out; the manifests of path dependencies outside the workspace; Cargo's configuration above the repository and in the Cargo home; environment variables; and the toolchain that rustup picks. A key that missed one would give a stale set of targets, for example a `build` whose outputs lack a new binary, which [[GOAL-TRUSTED-CACHE]] does not allow. The plugin therefore requests each report afresh in every graph computation and keeps none between computations, in the Nx daemon either.
55
+
56
+ Rejected: a report stored in Nx's workspace data folder, or kept in the daemon's memory, under such a key. It would save at most about 0.15 s per computation on the largest workspace measured, it needs helpers that Nx exports only as internals ([[RISK-UPSTREAM-CHANGES]]), and every gap in the key would be a wrong graph.
57
+ :::
58
+
59
+ :::mara decision ADR-MULTI-WORKSPACE
60
+ :mid: 01M78FHG7FZZT4VV8SYT01Z2B2
61
+ :title: Support several Cargo workspaces through a workspace context
62
+ :status: accepted
63
+ :justifies: REQ-MULTI-WORKSPACE
64
+ :justifies: DES-DISCOVERY
65
+
66
+ Repositories that add Rust to an existing monorepo rarely have one Cargo workspace at the Nx root: they have a workspace in a subfolder, tools as standalone crates, and sometimes several workspaces. Requiring one root workspace would force a restructuring before the plugin can be tried. The plugin supports any number of workspaces anywhere, and hangs everything Cargo scopes to a workspace off one [[TERM-WORKSPACE-CONTEXT]]: lockfile, build directory, toolchain file, batch and coverage database. Standalone crates are workspaces of one and share no build directory; the plugin does not hide that.
67
+ :::
68
+
69
+ :::mara decision ADR-PROJECT-NAMES
70
+ :mid: 01M78FHG7FAG0YENBEH7FQ7WX1
71
+ :title: Name projects after crates and fail on a collision
72
+ :status: accepted
73
+ :justifies: REQ-PROJECT-NAMES
74
+
75
+ The crate name is what a Rust developer types, so it is the Nx project name. With several workspaces two crates can share a name. Deriving unique names automatically, for example from paths, would make names unpredictable and would change them when a second crate appears. A collision is therefore an error naming both paths, and the user fixes it with a per-crate name or a per-workspace prefix in metadata. Because commands always use the real package name and manifest path, the Nx name is free to differ. A crate whose folder also is a JS project is the exception. Nx applies `package.json` and `project.json` after every plugin, so the name set there wins, and neither the crate name nor its `name` override can change it ([[EVD-NX-PROJECT-MERGE]]).
76
+ :::
77
+
78
+ :::mara decision ADR-WORKSPACE-PROJECT-NAME
79
+ :mid: 01M7A8AKF5KKZ457ED2PX0NX4D
80
+ :title: Name the workspace project after its folder's path
81
+ :status: accepted
82
+ :justifies: REQ-PROJECT-NAMES
83
+ :justifies: REQ-METADATA-OVERRIDES
84
+ :justifies: DES-PROJECT-GRAPH
85
+ :justifies: DES-METADATA-TABLES
86
+
87
+ Agreed with the maintainer on 13 November 2026, for a [[TERM-WORKSPACE-PROJECT]] whose root manifest defines no crate. Cargo has no name for a workspace ([[EVD-WORKSPACE-PROJECT-NAMES]]), so the plugin derives one: the path of the workspace folder from the root of the Nx workspace, with each `/` replaced by `-`. Such a name is determined by the workspace's folder alone: it needs no configuration and does not depend on which other workspaces or crates exist, so it does not change when one appears, and the objection of [[ADR-PROJECT-NAMES]] to names derived from paths does not apply. Nx also accepts the folder itself where a project name is expected. The root of the Nx workspace has no such path, and its folder name differs between checkouts, so a workspace there is called `cargo-workspace`. Rejected: the folder's last segment, which is Nx's own default for a `project.json` without a name but lets `a/rust` and `b/rust` collide; the path with a `-workspace` suffix, which collides less often but is longer; one fixed name, which every workspace after the first would have to override; `rust` at the root, which a workspace in `rust/` gets too; and the name in the root `package.json`, which would name a Cargo project from a JS file. The names are not unique. `services/billing/` and `services-billing/` both give `services-billing`, the root and a folder `cargo-workspace/` both give `cargo-workspace`, and a folder named like one of its own crates gives that crate's name. Each of these fails like any other collision between two projects of this plugin, and the `name` in `[workspace.metadata.nx.project]` resolves it.
88
+
89
+ A collision between any two of the plugin's projects, crates or workspace projects, fails with the plugin's error, so that the user learns both manifests and both remedies; one with a JS project stays Nx's error, as for crates. The override is the sub-table `[workspace.metadata.nx.project]`, holding the `name`, `tags` and `targets` of a package table, because [[ADR-METADATA-KEY]] makes the `nx` table hold what a `project.json` holds while the workspace table's own keys are defaults for the members. Rejected: `workspaceProject`, which is long; `root`, which Nx uses for a project's folder; and a flat `name` in the workspace table, which reads as a default for members and leaves the project's own targets without a place. When the root manifest defines a crate, that crate's table already configures the project, so the sub-table is an error instead of a second place for the same settings. The workspace's name prefix stays with the members, whose names it separates; a workspace project's default name comes from its folder, and a collision of that name is resolved with the project's own `name`. Names are neither checked nor rewritten beyond `/` to `-`: Nx accepts any string, and the characters that are awkward on its command line are rare in folder names and fixed with the override. Where the workspace folder already is an Nx project, Nx merges the two and names the result ([[EVD-NX-PROJECT-MERGE]]); the plugin accepts that as it does for a crate, because [[REQ-WORKSPACE-PROJECT]] fixes the project's root.
90
+ :::
91
+
92
+ :::mara decision ADR-ALL-DEP-KINDS
93
+ :mid: 01M78FHG7F89HNQ2GAMHTHFRC2
94
+ :title: Keep every dependency kind in the graph, including cycles
95
+ :status: accepted
96
+ :justifies: REQ-DEPENDENCY-EDGES
97
+ :justifies: DES-PROJECT-GRAPH
98
+
99
+ Leaving dev-dependencies out of the graph means a change in a crate used only by another crate's tests does not invalidate those cached tests. All three kinds are therefore edges.
100
+
101
+ Cargo allows cycles through dev-dependencies. Three treatments were considered: drop the edge that closes the cycle and add the crate's files as explicit inputs, fail graph creation, or keep the edge. Nx 24 fails only on a cycle between tasks, not between projects ([[EVD-NX-24-INSPECTION]]), and the plugin's targets declare no dependencies between crates beyond the lockfile task, which depends on nothing ([[ADR-NO-RUST-BUILD-DEPS]]). The edge is kept, so `nx graph` shows at least what Cargo sees and no workspace that Cargo accepts is rejected. The exception is an edge to a crate that `[patch]`, `[replace]` or `paths` redirects to and that reaches the edge's source through normal or build dependencies: Cargo rejects that cycle, so the edge is left out and inputs cover the source's dev-dependencies ([[ADR-REDIRECTION-EDGES]]). If a user's own `dependsOn` turns the project cycle into a task cycle, Nx reports it. Nx 24 hashes `^` inputs over a project cycle stably ([[EVD-NX-24-INPUT-SEMANTICS]]).
102
+ :::
103
+
104
+ :::mara decision ADR-EXTERNAL-NODES
105
+ :mid: 01M78FHG7FYRBX038BA9MX7YXN
106
+ :title: Represent external crates as graph nodes
107
+ :status: retired
108
+
109
+ With the whole `Cargo.lock` as an input, any dependency update invalidates every crate of the workspace. Each direct external dependency becomes a node with the prefix `cargo:` instead, so a crate can be hashed on the dependencies it uses. This is agreed in principle; the hashing mechanism is not designed yet.
110
+
111
+ Neither is the identity of a node. Several workspaces have several lockfiles, and one lockfile can hold several versions of a crate, so a name without a version cannot stand for all of them. The nodes are therefore created only together with the hashing design, and until then the whole lockfile stays an input.
112
+
113
+ Retired on 13 November 2026: v1 creates no external nodes. Nx 24 keys crates correctly through such nodes, but `nx affected` ignores them after a change to `Cargo.lock` alone ([[EVD-NX-24-EXTERNAL-NODES]]). [[ADR-LOCKFILE-TASK]] replaces this decision.
114
+ :::
115
+
116
+ :::mara decision ADR-LOCKFILE-TASK
117
+ :mid: 01M7ACCPE3JYNPZCK42RZG5H3H
118
+ :title: Key crates on a lockfile task per workspace, not on external nodes
119
+ :status: accepted
120
+ :justifies: REQ-EXTERNAL-DEPS
121
+ :justifies: DES-LOCKFILE-HASHING
122
+ :justifies: REQ-NO-RUST-TASK-DEPS
123
+ :supersedes: ADR-EXTERNAL-NODES
124
+
125
+ With the whole `Cargo.lock` as an input, any dependency update invalidates every crate of the workspace. [[ADR-EXTERNAL-NODES]] planned a graph node with the prefix `cargo:` for each external dependency, so that a crate's key could follow the dependencies it uses. In Nx 24.0.6 such nodes key the crates correctly, but `nx affected` then selects no crate after a change to `Cargo.lock` alone: Nx works out which external nodes moved only for JS lockfiles, and a plugin has no way to tell it ([[EVD-NX-24-EXTERNAL-NODES]]). A pipeline that runs `nx affected` would skip Rust on every dependency update. The nodes would also reach JS projects: a target without an `externalDependencies` input hashes every external node of the graph, so each change to a `Cargo.lock` would invalidate the `package.json` scripts of every JS project.
126
+
127
+ Each workspace therefore has one task that reads its `Cargo.lock` and writes, for each crate, a digest of the packages the crate reaches. Every cached target of a crate depends on that task and hashes the crate's digest, or the digests of all members where the crate is built with the features of the whole workspace (below). A change to `Cargo.lock` reaches the task through its file input, and Nx selects every task that reads the task's output, so `nx affected` selects the crates of that workspace, and those whose digest did not change are restored from the cache ([[EVD-NX-24-LOCKFILE-TASK]]). `nx affected` selects more than it must and the keys select exactly, which is the trade [[GOAL-TRUSTED-CACHE]] asks for. Under the feature strategies that build with the whole workspace's features, a crate's key holds the digests of all members, because a package that only another member reaches can change the features of a dependency they share; there a change that moves any member's digest runs every crate of the workspace again ([[DES-INPUTS]]), and the check after a task's cargo calls compares every digest that its key holds, not only its crate's own ([[DES-LOCKFILE-HASHING]], "Post-check").
128
+
129
+ A digest describes what cargo builds only while cargo calls the lockfile current. A stale lockfile cannot be keyed by its files at all: on identical files, cargo resolved a new dependency to another version once a newer one was published ([[EVD-CARGO-LOCK-CHECK]]). The task therefore first runs `cargo update --workspace`. That leaves a current lockfile alone and brings a stale or missing one up to date exactly as the crates' own cargo commands would, so adding a dependency and running `nx build` works as with plain cargo; in locked mode it fails instead. The task is not cached, because cargo's verdict also depends on files outside the repository, which Nx cannot hash, and Nx 24 keeps a result out of the cache only when the task fails ([[EVD-NX-24-LOCKFILE-UPDATE]]).
130
+
131
+ Rejected: external nodes alone, for the reasons above; external nodes for the keys together with a task of constant output for `nx affected`, which works but keeps the invalidation of JS projects and needs node names that tell apart versions and lockfiles; a digest in a target option, which keys correctly but which `nx affected` never selects; the whole lockfile, which does not meet [[REQ-EXTERNAL-DEPS]]; a comparison of manifests with lockfile entries written by the plugin, which missed cases that cargo catches; failing the task on a stale lockfile, which breaks adding a dependency and building; and running the crates of a stale workspace uncached under keys that never repeat, which runs them twice and fills the cache with entries nothing reaches.
132
+
133
+ The costs are one cargo call per workspace in every run that includes a cached crate task, also when every crate is then restored from the cache, and index fetches on a cold cargo home; a rewrite of `Cargo.lock` in a run where every crate task is then restored, which is cargo's own write ([[REQ-NO-MANIFEST-WRITES]]); a dependency of crate targets on a target of another project, the first exception that [[REQ-NO-RUST-TASK-DEPS]] makes, the drift check of the `hakari` strategy being the second; a graph that shows no external crates; and reliance on how Nx 24 selects the tasks that read a producer's output, which a later Nx major could change. The end-to-end checks of [[VER-CACHE-KEYS]] cover that selection, and a later major is supported only once they pass ([[ADR-COMPATIBILITY]]).
134
+ :::
135
+
136
+ :::mara decision ADR-METADATA-KEY
137
+ :mid: 01M78FHG7FQK38H3AQ3ZN130A0
138
+ :title: Keep overrides under the nx key of Cargo metadata
139
+ :status: accepted
140
+ :justifies: REQ-METADATA-OVERRIDES
141
+ :justifies: DES-METADATA-TABLES
142
+ :accepts: RISK-METADATA-KEY-COLLISION
143
+
144
+ Overrides live in `Cargo.toml`, next to what they override, in `[package.metadata.nx]` and `[workspace.metadata.nx]`. The key `nx` mirrors the `nx` property that Nx reads from `package.json` and holds what a `project.json` would hold, which is short and familiar to Nx users. The alternatives were `nx-rust`, named after the package as Cargo tools usually do, and a split between `nx` for project settings and `nx-rust` for plugin switches. `nx` was chosen with the known cost that another Nx plugin for Rust could claim the same key.
145
+ :::
146
+
147
+ :::mara decision ADR-NX-TARGET-NAMES
148
+ :mid: 01M78FHG7FTBB2RVZTTTWPYG1P
149
+ :title: Use Nx target names by default
150
+ :status: accepted
151
+ :justifies: REQ-TARGET-NAMES
152
+ :justifies: DES-TARGETS
153
+ :accepts: RISK-TARGET-DEFAULTS
154
+
155
+ The plugin is written first for mixed JS/TS and Rust repositories, whose pipelines run `nx affected -t lint test build`. With Cargo's names, clippy would be skipped until every pipeline adds `clippy`. Inferred targets therefore use the Nx name where Nx projects conventionally have a target for the same job: clippy runs as `lint`, and `test` and `build` keep their names. Every name can be changed in the plugin options, so Cargo's names are an opt-in. The cost is that target defaults written for JS targets of the same name also reach Rust targets.
156
+
157
+ Formatting was decided separately. Nx has a convention for it, but it is the built-in commands `nx format:check` and `nx format:write`, not a target. They run prettier or oxfmt over files and cannot be made to run rustfmt in Nx 24 ([[EVD-NX-FORMAT]]). Naming the rustfmt targets `format-check` with `format-write` or `format` was considered. They keep Cargo's names, `fmt-check` and `fmt`, so that nobody takes them for that command: `format` is a reserved command name, and `nx format <project>` would silently run Nx's formatter instead of `cargo fmt`.
158
+
159
+ `check` has a counterpart: `typecheck`, which the TypeScript plugin of `@nx/js` infers and which the CI workflow that Nx generates runs beside `lint`, `test` and `build` ([[EVD-NX-24-TARGETS]]). It keeps Cargo's name all the same. That pipeline already runs `lint`, and clippy checks everything `cargo check` does, so a Rust `typecheck` would only check every affected crate a second time; clippy does not reuse what `cargo check` compiled for the crate itself ([[EVD-CARGO-TARGET-COMMANDS]]). A repository that wants the name can rename the target. The remaining targets (`doc`, `bench`, `run`) and the targets of the workspace project (`audit`, `deny`, `update`) have no Nx counterpart and keep the names of Cargo and the tools.
160
+ :::
161
+
162
+ :::mara decision ADR-NO-RUST-BUILD-DEPS
163
+ :mid: 01M78FHG7FCE6NXVG4J9K82XME
164
+ :title: Put no build dependencies between Rust crates
165
+ :status: accepted
166
+ :justifies: REQ-NO-RUST-TASK-DEPS
167
+ :justifies: DES-TARGETS
168
+
169
+ Cargo builds a crate's dependencies itself, so a `dependsOn: ["^build"]` between crates adds no ordering that is needed. It only starts one cargo process per dependency, and they queue on the build lock ([[EVD-NXRUST-BUILD-DEPS]]). Invalidation is handled by `^` inputs. JS consumers of an artifact depend on the artifact target.
170
+
171
+ The first design also made `^build` on edges from JS projects to Rust crates an opt-in. Nx leaves no room for that: a JS target that declares `^build` gets the `build` task of every project it depends on that has such a target, and neither the plugin nor the dependency can decline ([[EVD-NX-24-INSPECTION]]). The plugin therefore adds no dependency to JS projects and removes none. A JS target's own `^build` runs the native `build` of the crates its project depends on directly and stops there, because those targets depend only on their workspace's lockfile task ([[DES-LOCKFILE-HASHING]]), which has no `build`. The cost is a native build that a consumer of a wasm package or a Node addon does not need; batching folds such builds into one cargo call ([[DES-BATCH]]). Renaming the native build so that `^build` would miss it was rejected, because `nx affected -t build` would then skip Rust ([[ADR-NX-TARGET-NAMES]]).
172
+
173
+ In a crate folder that also is a JS project, a `package.json` script, a `project.json` target or a plugin listed after nx-rust can replace the crate's `build` ([[REQ-MIXED-PROJECTS]]). That target is not the plugin's any more, and the plugin adds nothing to it and removes nothing from it either. Where it depends on `^build`, as the TypeScript plugin's `build` does or as a `targetDefaults` entry keyed `build` gives it, a JS consumer's `^build` runs it and, through it, the native `build` of the crates that the mixed project depends on directly, which stop at their workspace's lockfile task ([[EVD-NX-MIXED-CONSUMER]]). That is one more level of native builds, which batching folds into one cargo call; it costs time and leaves results correct.
174
+ :::
175
+
176
+ :::mara decision ADR-MIXED-PROJECT-TARGETS
177
+ :mid: 01M7J4NJ5W2KQHV5E6A7CT2CS2
178
+ :title: Leave a crate's targets to the JS files of its folder
179
+ :status: accepted
180
+ :justifies: REQ-MIXED-PROJECTS
181
+ :justifies: DES-MIXED-PROJECTS
182
+
183
+ A crate folder that also is a JS project gets the plugin's targets under their usual names, and Nx lays the folder's `package.json` and `project.json`, and the plugins listed after nx-rust, over them by its own rules ([[EVD-NX-PROJECT-MERGE]]). The plugin neither renames an inferred target that one of them also defines nor reports that it was replaced. Decided on 16 November 2026 for the maintainer from the accepted items, as the specification of milestone 0.4 (nxr-ym403k); listed in the review of the decisions made in 0.4.
184
+
185
+ - **Why the folder's files win.** [[REQ-METADATA-OVERRIDES]] gives them precedence over the crate's Cargo metadata, and the guard reads them as the project's own statement ([[DES-TARGET-DEFAULT-GUARD]], "Other layers", decided by the maintainer on 15 November 2026). A napi crate's `build` script that runs `napi build`, or a TypeScript build, is what the folder's author wrote `build` for.
186
+ - **Not chosen: renaming the inferred target where a name collides.** The names of a crate's targets would then depend on its folder's JS files, so that `nx affected -t build` and `nx run-many -t test` would cover different work in different crates ([[REQ-TARGET-NAMES]]), and the plugin never renames on its own ([[REQ-PROJECT-NAMES]]). Whoever wants both renames one: the script, or the plugin's target through `targetNames`.
187
+ - **Not chosen: reporting the collision.** The napi-rs project template gives every addon's `package.json` the scripts `build` and `test`, so a warning would fire in the common setup on a deliberate configuration, and an error would stop it. A replaced target runs its own command under its own key, so it cannot hand Nx a result that cargo would not give; what can, a later layer that keeps the plugin's executor and narrows its lists, the guard already reports.
188
+ - **Nx's own means are the remedy.** `nx.includedScripts` in the `package.json` keeps scripts out of the targets, and the order of the plugins in `nx.json`, where `nx add` appends a new plugin, decides between two plugins' targets ([[EVD-NX-MIXED-CONSUMER]]).
189
+
190
+ The lockfile task of a workspace whose folder already is an Nx project can be replaced in the same way, and then the crates' cached tasks find no digest. They fail without storing a result ([[DES-LOCKFILE-HASHING]], "Merged project"), so this needs no check of its own either; renaming the lockfile task through `targetNames` resolves it.
191
+
192
+ To undo: a warning for a replaced inferred target can be added later without breaking a repository; renaming targets automatically would change names users already run.
193
+ :::
194
+
195
+ :::mara decision ADR-RESULTS-ONLY-CACHE
196
+ :mid: 01M78FHG7FYVQP1W5GZC509GEF
197
+ :title: Cache task results and final artifacts, never Cargo's intermediates
198
+ :status: accepted
199
+ :justifies: REQ-CACHE-OUTPUTS
200
+ :justifies: DES-OUTPUTS
201
+ :justifies: DES-BUILD-DIRS
202
+
203
+ Cargo's build directory is large, its layout is internal and changes between Cargo versions, and restoring parts of it from another run confuses Cargo's own freshness checks. Nx therefore stores what a consumer needs: the result of a check or test, and the final artifacts of a build. Cargo keeps its build directory, which CI caches as a whole. A cache hit on `build` gives back a binary, not a warm compiler state; the next real compile relies on the build directory.
204
+
205
+ Final artifacts are the files that something other than Cargo consumes: executables, and `cdylib` and `staticlib` libraries. An `rlib` or `dylib` only feeds further Rust compilation and stays Cargo's. Nx can store only files inside the repository, so where the artifact directory lies outside it, the targets that would store artifacts run uncached. Caching their result without the files would restore a build that has no binary.
206
+ :::
207
+
208
+ :::mara decision ADR-DECLARED-INPUTS
209
+ :mid: 01M78FHG7FGX22WZF138Z8K89G
210
+ :title: Describe cache keys with declared inputs, not a custom hasher
211
+ :status: accepted
212
+ :justifies: DES-INPUTS
213
+ :justifies: REQ-ENV-ALLOWLIST
214
+
215
+ Nx deprecates custom hashers and plans to remove them in Nx 25 ([[EVD-NX-24-INSPECTION]]). Task-based affected, the default in Nx 24, selects tasks by matching changed files against their declared inputs, so complete file inputs are also what make `nx affected` correct. Environment and runtime inputs only change keys: a change to them alone makes no task affected ([[EVD-NX-24-INPUT-SEMANTICS]]). All cache inputs are therefore declared: filesets, `^` inputs, environment variables, runtime commands and target options. Environment variables come from a fixed, extendable list, never the whole environment, because a key that includes everything never repeats.
216
+
217
+ For files the choice goes the other way. The whole folder of a crate is an input, not a list of source folders. A list would invalidate less, but it misses what macros and build scripts read: a README included as crate documentation, templates, migrations, protocol definitions, and sources at a path the manifest names. Running a crate's tasks again after a change that could not affect them is the accepted side of that trade. A negated pattern in the repository's own configuration takes files out of the folder's input, on the repository's responsibility.
218
+ :::
219
+
220
+ :::mara decision ADR-BATCH-EXECUTOR
221
+ :mid: 01M78FHG7F9MD0KQ68Y5CC4HK5
222
+ :title: Run tasks through an Nx batch executor
223
+ :status: accepted
224
+ :justifies: REQ-BATCHING
225
+ :justifies: DES-BATCH
226
+ :accepts: RISK-BATCH-BEHAVIOUR
227
+
228
+ Nx decides what runs and what is cached, per crate. Cargo should still be invoked as few times as possible, because each invocation takes the build lock and resolves the workspace again. An executor with `batchImplementation` and `preferBatch: true` gets both: Nx hashes, restores and caches each task, and the plugin serves each group of tasks with one cargo call for each step of their target, not one per crate. `build` and `doc` run through a second such executor, because Nx stores a batch's outputs only when the whole batch has ended and would otherwise store what a later `cargo test` of the same batch wrote ([[ADR-TEST-AFTER-BUILD]]). The known cost is that Nx starts no other task while a batch runs.
229
+ :::
230
+
231
+ :::mara decision ADR-TASK-NAME-VARIABLES
232
+ :mid: 01M7FZHXES8CVY46H25QJG3BV7
233
+ :title: Leave out of cargo's environment the two variables by which Nx names a task's project
234
+ :status: accepted
235
+ :justifies: DES-BATCH
236
+
237
+ [[TERM-GROUP]] gives the tasks of a group one environment, and cargo got each task's environment with the per-task variables that are the same in every way of running the task, among them `NX_TASK_TARGET_PROJECT` and `LERNA_PACKAGE_NAME`, which Nx sets to the task's project ([[EVD-NX-24-BATCHES]], "Task environment"). Of what Nx 24 sets for a task after its dotenv files (`getNxEnvVariablesForTask` in `tasks-runner/task-env.js`), only these two differ between tasks of one target and configuration: `NX_TASK_TARGET_TARGET` and `NX_TASK_TARGET_CONFIGURATION` name the target and the configuration, and `NX_TASK_HASH` is left out already. So no group could hold two crates: a batch under `workspace-build` ran `nx run-many -t test -p a b` as six cargo commands, three for each task, where [[REQ-BATCHING]] asks for three (nxr-8f9dz2, 15 November 2026), and one cargo command cannot give its build scripts and tests the values of two crates.
238
+
239
+ The maintainer decided on 15 November 2026, asked what cargo, build scripts and Rust tests should see, "Leave out those two variables (Recommended)": cargo never gets `NX_TASK_TARGET_PROJECT` and `LERNA_PACKAGE_NAME`, whether a task runs on its own or in a batch, in any output style, so that the tasks of one target share an environment and a command, and no result can depend on a value that only some ways of running would give. The other variables of Nx's per-task layer, the target's name and the configuration, stay. A build script or test that needs to know its crate reads `CARGO_PKG_NAME`, which cargo sets. Not chosen: leaving out every variable that names the task, the target and the configuration too, which take nothing from the sharing, and keeping them all, with which no group would ever hold two crates.
240
+ :::
241
+
242
+ :::mara decision ADR-WORKSPACE-TEST-EXECUTABLES
243
+ :mid: 01M7FZHXESE3W8G8747SRPX9GP
244
+ :title: Let a test of the whole workspace wait for the builds whose executables it writes
245
+ :status: accepted
246
+ :justifies: DES-TARGETS
247
+ :justifies: REQ-NO-RUST-TASK-DEPS
248
+
249
+ Under `workspace-build`, every step of a `test` group selects the whole workspace ([[DES-TEST-RUN]], "Under `workspace-build`"), and a `cargo test` that selects the whole workspace replaces the executables that the `build` of every crate with a binary and an integration test or bench stores, not only those of the group's crates, on Cargo 1.91.0 and 1.100.0 ([[EVD-CARGO-ARTIFACT-WRITERS]], "Commands that select the whole workspace"). [[DES-TARGETS]] ordered a crate's `test` after its own `build` only. Within one batched command, Nx awaits each batch and stores the `build` batch before it starts anything else ([[EVD-NX-24-BATCHES]]); but where tasks run on their own and at the same time, as with `--batch=false` or `NX_BATCH_MODE=false`, which [[DES-BATCH]] offers for a task that waits for a signal, the `test` of one crate could run while the `build` of another runs or is being stored, and Nx could store the executable of `cargo test` under that build's key, which [[GOAL-TRUSTED-CACHE]] excludes.
250
+
251
+ The maintainer decided on 15 November 2026, asked what should prevent that, "Tests wait for those builds (Recommended)": under `workspace-build`, a crate's `test` depends on the `build` of each crate of its workspace whose executables a `cargo test` of the whole workspace replaces, so that Nx orders them in every mode, also with `--batch=false` or `NX_BATCH_MODE=false`. The crates are those of the rule of [[DES-TARGETS]], applied to every member with a project: a binary and a target of kind `test` or `bench` whose `test` flag is on, whatever the `required-features`. That rule counted, in the fixture with one crate of each shape, the four crates whose executables the command replaced and one more whose binary needs a feature, and no `cdylib`, `staticlib` or example; it is the rule that ordered a crate's `test` after its own `build`, which becomes one case of it, so that one rule and one guard cover both. It is a third exception of [[REQ-NO-RUST-TASK-DEPS]].
252
+
253
+ What it costs: `nx test <crate>` also runs or restores the `build` of those crates. Nx counts a task's dependencies in its key and in `nx affected`, so a change to the inputs of such a crate's `build` runs every `test` of the workspace again, and `nx affected -t test` selects them all; under `workspace-build` those tests share their cargo commands, which build the whole workspace anyway. Not chosen: failing a `test` that starts while such a `build` is unfinished, which fails an ordinary `nx run-many -t build test` with batching off; refusing `test` under `workspace-build` outside a batch, which leaves `--batch=false` and `NX_BATCH_MODE=false` without a way to run tests; and accepting the overlap as part of [[RISK-ARTIFACT-DIR-WRITERS]], which stores wrong entries.
254
+ :::
255
+
256
+ :::mara decision ADR-STAGED-BUILDS
257
+ :mid: 01M7X59APKESA509GHH54BNQW7
258
+ :title: Build the whole workspace, and compile artifact targets, into a stage, and move only the task's own files into the artifact directory
259
+ :status: accepted
260
+ :justifies: DES-BATCH
261
+ :justifies: DES-BUILD-DIRS
262
+ :justifies: DES-INVOCATION
263
+ :justifies: DES-OUTPUTS
264
+ :justifies: REQ-CARGO-UNCHANGED
265
+
266
+ A `build` that selects the whole workspace links the executables, `cdylib` and `staticlib` files of every member again, also of fresh units, with its own environment and feature set ([[EVD-CARGO-ARTIFACT-WRITERS]]). Two builds of one Cargo workspace whose commands differ, such as through a crate's own `RUSTFLAGS` in a dotenv file or its own feature set, therefore replace each other's files on disk within one command. This happens after a build of an earlier wave of a batch, after a build that Nx restored before the batch, and with batching off. A cached task that runs such an executable, such as a packaging step, then stores a result made from the wrong build ([[EVD-BATCH-FILES-ON-DISK]]). The first remedy kept the other builds' files and put them back after each later group (commit 41c2299 of nxr-yfh7zh). Its review found a window: while the later group's cargo runs, the files on disk are the other variant, and a task that is already running, or a continuous task that Nx starts between two waves of a batch, reads it. Leaving a group for a following batch also gave the build left out a key computed before its dependencies had run, and the review got a wrong cache hit from it (nxr-f04xen; [[EVD-STAGED-BUILDS]]).
267
+
268
+ The maintainer decided on 20 November 2026. He was asked: "nxr-yfh7zh: two builds of one Cargo workspace whose commands differ (a crate with its own RUSTFLAGS in a dotenv file, or its own feature set) replace each other's executables on disk within one command, so a cached task that runs such an executable (a packaging step) can store a result made from the wrong build. The fix that was built (keep the files, put them back afterwards) leaves a window. How should builds be made safe?" He chose "Stage artifacts (Recommended)". As described to him, whole-workspace `build` and `napi-build` run cargo with `--target-dir <stage>` and `build.build-dir` set to the real directory, then move only their own crates' final files into the artifact directory. This leaves no window, also fixes batching off, and removes the leaving of a build for a later batch together with its confirmed wrong cache hit. `REQ-CARGO-UNCHANGED` and `DES-INVOCATION` are amended: two more cargo flags, visible with `--verbose`. `nx build pa` no longer refreshes other crates' executables in `target/`. Two configurations of one crate into one folder fail with guidance instead of sharing a command. It is a new high-risk piece of work that starts with a spike, and the keep-and-put-back remedy for builds is dropped. Not chosen: refusing such commands, keeping and putting back, and stating the limit only.
269
+
270
+ The spike confirmed on cargo 1.91.0 and 1.100.0 what the choice relies on ([[EVD-STAGED-BUILDS]]). With the stage and the build directory that cargo would use anyway, a staged build reuses plain cargo's work and plain cargo reuses the staged build's. It writes nothing into the artifact directory and reports the exact paths of its files in the stage. Build scripts keep their `OUT_DIR` in the build directory, and the plugin sets no `CARGO_TARGET_DIR` for them. Cargo's build lock keeps serializing commands. `wasm-build`, whose compile and post-processing work like `napi-build`'s, is staged as well. `cargo test` cannot be: it fixes the stage's path into `CARGO_BIN_EXE_<name>` without counting it in the fingerprint, so a later plain `cargo test` runs a missing executable. A `test` or `bench` batch therefore keeps and puts back the builds' files, as [[ADR-TEST-AFTER-BUILD]] records. [[DES-BATCH]] ("Staged builds") describes the design.
271
+
272
+ The control plane settled two questions of the design on 20 November 2026, of which the maintainer is told. The stage lies in the artifact directory, as `.nx-rust-stage/<process id>-<counter>`, rather than in Nx's `.nx/workspace-data`: on the file system of the files it replaces, among Cargo's directories, which the build input check leaves out and where cargo 1.91.0 spells generated files in the stage's records, and removed by `cargo clean`; a marker with the process's start time tells a stage left by a dead process from a live one's, also where the id was reused ([[DES-BATCH]], "Staged builds"). Whether a process runs is judged in the process namespace of the command that looks, so commands in separate containers that share one artifact directory can remove each other's live stage. And where a group of a batch fails, the later groups of the same batch process still run and are stored, also under `--nx-bail`, which Nx 24 does not tell a batch. The maintainer confirmed this one on 21 November 2026, agreeing ("Agree with recommendation") that it stands as a documented limitation of Nx until Nx passes the flag to a batch.
273
+
274
+ What it costs: two flags on the commands concerned, which a verbose run prints; a build of the whole workspace that no longer refreshes the final artifacts of members whose `build` the command does not run; a `.nx-rust-stage` folder in the artifact directory while such a command runs, and after an interrupted one until the next; and the refusal of two `build` tasks of one crate whose files lie in one folder. Not chosen earlier for nxr-yfh7zh: a later group that selects only its own crates, which changes the features that cargo resolves for a crate depending on what else the batch holds, against [[REQ-STABLE-FEATURES]]; and failing such tasks with a message to run them in separate commands, which takes away what users can run today.
275
+
276
+ A stage has a second use since 21 November 2026 (nxr-5hzxra): a `test` or `bench` group of a batch holds in one the files of the command's cached builds that its cargo commands link again, as hard links, and puts them back from it when it ends ([[ADR-TEST-AFTER-BUILD]], [[DES-BATCH]], "Files that a test batch puts back"). It builds nothing there, and `cargo test` still runs with the artifact directory that cargo uses anyway. The orchestrator chose the stage after the review of the first implementation, which kept the files under second names beside them, where a batch killed while it ran left them for a later build with a folder or glob output to store; a stage left so is removed by the next staged command or test group that keeps files, as for a build.
277
+ :::
278
+
279
+ :::mara decision ADR-WORKSPACE-FEATURES
280
+ :mid: 01M78FHG7F9M47HN1VS68YT9K3
281
+ :title: Never resolve features for whichever crates happen to be selected
282
+ :status: accepted
283
+ :justifies: REQ-STABLE-FEATURES
284
+ :justifies: DES-UNIFICATION
285
+ :justifies: DES-FEATURE-SETS
286
+
287
+ A batch of whatever is affected changes the set of crates built together on every run. Because of [[TERM-FEATURE-UNIFICATION]], that changes the features of shared dependencies, which causes rebuild churn and makes a crate's result depend on its batch. The plugin therefore resolves features for the whole workspace on every run, for every group of tasks that shares a cargo command. Three strategies do this at different costs: `hakari` where the workspace already uses cargo-hakari, Cargo's own `feature-unification` setting as an experimental opt-in, and building the whole workspace as the fallback that always works. Where a shared command would make features follow the selection all the same, because its flags act on the selected crates or because its triple cannot be built for the whole workspace or is not one that the hack crate covers, each task runs its crate alone instead, so that its features follow from its own crate and its result from what its own key holds. That costs speed and can compile a shared dependency in more than one variant, but never a result; the control plane decided it on 14 November 2026, of which the maintainer is told ([[DES-BATCH]], "Groups of one crate").
288
+ :::
289
+
290
+ :::mara decision ADR-ONE-TEST-TARGET
291
+ :mid: 01M78FHG7FWYPHVZ9TAHHZ0A5N
292
+ :title: Keep one test target and put the mode in the cache key
293
+ :status: accepted
294
+ :justifies: REQ-AFFECTED-TESTS
295
+ :justifies: REQ-TEST-MODE-KEY
296
+ :justifies: DES-TEST-MODE
297
+
298
+ Affected-test selection could be a second target beside `test`. Users would then have to know which one to run where, and pipelines would differ between branches. Instead there is one `test` target that decides inside whether to run a subset or the full suite. What keeps the cache honest is the [[TERM-TEST-MODE]] in the key: a runtime input that prints `full` or `affected:<baseline commit>`.
299
+ :::
300
+
301
+ :::mara decision ADR-TEST-MODE-CHOICE
302
+ :mid: 01M78NVF8E9Q5SD8FDP09ADE2D
303
+ :title: Let the consumer choose the test mode, with a default per environment
304
+ :status: accepted
305
+ :justifies: DES-TEST-MODE
306
+ :justifies: REQ-AFFECTED-TESTS
307
+
308
+ The first design said the mode is `full` on the main branch and `affected` elsewhere. The plugin cannot tell reliably which of the two it is on: CI checkouts are detached or shallow, pull requests are tested on merge commits, and release branches and merge queues are neither. Asking Git whether HEAD is contained in the default branch was considered and rejected for the same reasons. The pipeline knows what it is running, so the consumer chooses: the environment variable `NX_RUST_TEST_MODE` names the mode of a run.
309
+
310
+ Two things follow. The `affectedTests` setting does not choose a mode. It declares that a workspace uses selection, which adds the baseline target and the mode input and makes every machine check the setup, so a missing tool shows on a developer's machine and not first in CI. And the default without the variable depends on where the run happens: `affected` on a developer's machine, so that local work gets selection without any setup, and `full` where Nx detects CI ([[EVD-NX-24-INSPECTION]]), so that a pipeline that sets nothing, such as the one for main, runs the whole suite. A pull request pipeline asks for `affected` explicitly.
311
+
312
+ An environment variable switches selection on, and not a command-line flag, because the command that puts the mode into the cache key can read the environment but not the `nx` command line. The flag `--affectedTests=false` can only force the full suite.
313
+ :::
314
+
315
+ :::mara decision ADR-TEST-SELECTOR
316
+ :mid: 01M78FHG7FH90JZ8ESEP4R4HCJ
317
+ :title: Use cargo-affected only to select and nextest to run
318
+ :status: accepted
319
+ :justifies: DES-TEST-RUN
320
+ :justifies: REQ-DOCTESTS
321
+
322
+ cargo-affected can both select and run tests, but it is very early and has no archive support. The plugin asks it for the selection only and runs the tests itself through nextest, which keeps per-crate results under the plugin's control, keeps the selector replaceable, and leaves room for a distributed mode. nextest does not run doctests, so they run through `cargo test --doc` whenever nextest is the runner; that is not optional.
323
+ :::
324
+
325
+ :::mara decision ADR-AFFECTED-TESTS-WIDENING
326
+ :mid: 01M7J59DN6SH9F9NGK13ETDBVZ
327
+ :title: Narrow by coverage only where coverage sees a change's whole effect, and widen by inputs everywhere else
328
+ :status: accepted
329
+ :justifies: DES-TEST-RUN
330
+
331
+ cargo-affected selects by the coverage that tests leave at run time. It lists the changed files without stored rows with `tracked_by_coverage: false` and selects no test for them ([[EVD-CARGO-AFFECTED-REPORT]]), and it misses tests that reach changed code through a program they start, as ripgrep's integration tests do with `rg`. A review of the first form of this decision found with plain cargo that the flag is no guide: a proc-macro crate with unit tests of its own has rows, and a change to it selected its own passing tests while a dependent's test of the generated code failed. The control plane decided on 16 November 2026, from [[REQ-SELECTION-SAFETY]] and [[GOAL-TRUSTED-CACHE]], the following, which step 2 of [[DES-TEST-RUN]] carries out.
332
+
333
+ - **By kind, not by rows.** Coverage narrows a changed file only where its whole effect on tests runs through code that coverage records at run time: a `.rs` file with rows in the workspace folder, of a member that is not a proc macro, that is not the member's build script and that no `fileInputs` pattern names. Every source file of a proc-macro crate, build scripts and the files that crates declare, every file other than Rust source, and a file without rows widen. The flag adds files to that set and never takes one out. Not taken: widening only the files that the flag marks, which the first form did and which passed a failing dependent.
334
+ - **Ownership by inputs, in the whole repository.** A widening file adds all tests of every crate of the group whose `test` task has it among its inputs, as the plugin infers them and the user declares them, through `^` inputs including the crates that depend on it. The plugin takes the changed files of the whole repository from git itself, while cargo-affected's own call keeps `diff.relative`. A file that is an input of no crate of the group adds nothing, and one that the plugin cannot place runs the full suite. Not taken: the first form's rule that only files in a member's folder count and that files outside the members' folders add nothing, which missed shared migrations, snapshots or schemas that a member declares, crates by path elsewhere in the repository, and configuration that `.cargo/config.toml` includes.
335
+ - **Programs that tests start.** A change among the inputs of a member with a binary target runs all integration tests of that member, and all tests of every member that depends on it by a Cargo dependency of any kind, an Nx dependency or declared inputs that reach its folder. Not taken: only the member's own integration tests, which the first form ran and which leaves a test in another crate that starts the binary unselected. A test that starts a program without any declared relation is outside what the plugin can see, and its cache key is already wrong without affected mode.
336
+ - **The limit that stays.** Code that another crate evaluates while it compiles, a `const fn` used in a `const` or a macro by example, leaves no row for that crate's tests. Widening every change to a library to all tests of all its dependents would end the narrowing altogether, so this stays a stated limit, said in the user guide next to the statement that an affected run never stands in for the full run ([[RISK-CARGO-AFFECTED]]). Not taken: that widening.
337
+ - **Build scripts that read Rust source.** A build script that reads a Rust file of its own crate is seen through `fileInputs`, which then widens that file; without the declaration a change to it narrows like other Rust code, and the user guide says so. Not taken: widening every Rust file of a crate with a build script, which would end the narrowing in every crate that has one.
338
+
339
+ To undo a rule, step 2 of [[DES-TEST-RUN]] drops it; nothing else depends on them.
340
+ :::
341
+
342
+ :::mara decision ADR-AFFECTED-BASELINE-CONTEXT
343
+ :mid: 01M7J8GXGNJ2X4GBGAJW7N0ZMS
344
+ :title: Trust a baseline only in the context it was collected in
345
+ :status: accepted
346
+ :justifies: DES-BASELINE
347
+ :justifies: DES-TEST-RUN
348
+
349
+ cargo-affected's fingerprint holds `Cargo.lock`, the workspace's manifests, `rustc -vV`, `RUSTFLAGS` and `CARGO_BUILD_TARGET` ([[EVD-CARGO-AFFECTED-REPORT]]), but not the features or profile of the command nor the environment variables that tests read. A review found with plain cargo that collecting without a feature and running with it, or changing a variable that `envInputs` declares, selected nothing and passed every check of the report, while the tests would have failed. The control plane decided on 16 November 2026, from [[GOAL-TRUSTED-CACHE]] and [[REQ-SELECTION-SAFETY]], that the plugin records beside the baseline the context of the collection that it knows and that changes what is compiled or run: the cargo options of the test command such as features and profile, the target triple, and a hash of the value of each environment input of the workspace's `test` tasks. Step 1 of [[DES-TEST-RUN]] compares the record with the task's own before it trusts a report. A difference, or a baseline without a record, runs the full suite, and the task says why. Not taken: relying on cargo-affected's fingerprint, which misses these, and adding them to it upstream, which the plugin cannot do. To undo it, [[DES-BASELINE]] stops writing the record and step 1 stops comparing.
350
+
351
+ The review of nxr-tabkjx found with the real cargo-affected that a declared runtime input reading a file outside the repository, collected with the file holding `good` and run with `bad`, selected no test in affected mode while the full suite failed. On 17 November 2026 the maintainer extended the rule: what git cannot show has to equal the collection's, so the record also holds, for every runtime input of the `test` tasks but the test mode command, the declared `runtimeInputs` and the plugin's own such as the toolchain command, a hash of the command's output, run as Nx runs it. Step 1 runs them again and compares; a different output, a command that fails, or a record without them runs the full suite and names the input. Undo: drop the field, which leaves a change outside git unseen.
352
+
353
+ The review of nxr-d0t9vm found with the real cargo-affected that the rule held for the test runs but not for the collection itself: a collection in another context chose `collect --diff`, re-collected nothing and wrote the new context's record beside coverage of the old one, so that an affected run in the new context left out a failing test. On 17 November 2026 the maintainer decided that the same comparison guards the collection: [[DES-BASELINE]] runs `--diff` only where the record that is there before the collection can be read, is of the current version and equals the context of this collection in every field, and collects everything into an empty database otherwise. No safe undo.
354
+ :::
355
+
356
+ :::mara decision ADR-TEST-SELECTING-RUNNER
357
+ :mid: 01M7DMTE8WN7QHDS5925MFCEVV
358
+ :title: Run a group's test binaries through a selecting runner and every doctest of the workspace where the whole workspace is built
359
+ :status: accepted
360
+ :justifies: DES-TEST-RUN
361
+ :justifies: DES-UNIFICATION
362
+ :accepts: RISK-TEST-RUNNER-MACOS
363
+
364
+ Under `workspace-build`, every step of a group of `test` tasks compiles with the features of the whole workspace ([[REQ-STABLE-FEATURES]]), and stable cargo has no flag that leaves out whole crates without resolving features for the rest: `-p` and `--workspace --exclude` both narrow them, and `resolver.feature-unification` needs a nightly flag ([[EVD-WORKSPACE-TEST-SELECTION]]). The maintainer chose on 14 November 2026 "Selecting runner (Recommended)". As put to him: with the default runner, one `cargo test --workspace --no-fail-fast` with a runner for the host on the command line, which cargo starts for every test binary and every doctest with the package's name in `CARGO_PKG_NAME`, and which runs the group's crates and exits with 0 for the rest; with nextest, `cargo nextest run --workspace` with the filterset `package(=a) | package(=b)` and `--no-tests=pass`, then the doctest step with the same runner. He was told what it costs: every run compiles the doctests of every library in the workspace; a compile error in any crate's tests fails every test task of the run; the plugin owns the runner and has to deal with a runner that the user configured; macOS is not verified ([[RISK-TEST-RUNNER-MACOS]]).
365
+
366
+ The options he did not take, as the research for the decision measured them:
367
+
368
+ - **Run everything and keep the group's results.** `cargo test --workspace --no-fail-fast`, with the other crates' results reduced to warnings. It needs nothing new, but every run runs every test of the workspace: 3.3 s against 1.3 s with the selecting runner and 0.09 s with `-p` in the research's workspace, where one test of another crate took 2 s. A test elsewhere that hangs, needs a service or has side effects holds up or disturbs the group.
369
+ - **The plugin runs the test binaries itself**, after `cargo build --workspace --lib --bins --tests --keep-going --message-format=json`. A compile error in another crate's tests would then fail only that crate. But the plugin would have to reproduce how cargo runs a test, with its folder, variables, library path, `[env]`, runner, output and summary of failures; a task would no longer run `cargo test` ([[VER-TESTING]]); and the doctests would still need another way, which a library that does not compile still stops.
370
+ - **No batching for tests.** One `cargo test -p` per task, with the features of its crate. It costs a cargo command per crate and further builds of shared dependencies beside the whole-workspace ones of `check`, `build` and `lint`, and would amend [[REQ-BATCHING]] and [[ADR-WORKSPACE-FEATURES]] for `test`.
371
+
372
+ **Four reviews, and the doctests.** Within his answer the control plane decided, of which the maintainer was told, how the runner works and how its results are checked. Four reviews of that design on 14 November 2026, and the experiments made for them, found wrong passes, and every one of them lay in the doctests: rustdoc counts any non-zero exit of a standalone `should_panic` doctest as a pass, so a runner that failed, a Node that did not start or a program that the loader could not load passed a doctest that never ran ([[EVD-TEST-RUNNER-EVIDENCE]]); with a runner, rustdoc runs merged edition-2024 doctests in one process, so that one that ended the process hid a failing one ([[EVD-TEST-RUNNER-EVIDENCE]]); a runner that ended with 0 before it recorded anything passed every program, which the check could only catch by comparing cargo's and rustdoc's human-readable output with the record ([[EVD-TEST-RUNNER-SILENT-EXIT]]); and terminal settings such as `CARGO_TERM_QUIET`, `[env]` and what tests print changed that output or the environment, so that the comparison passed vacuously or failed good runs. The maintainer had answered on the way that a standalone `should_panic` doctest ending without an unwinding panic should fail with an explanation ("Fail it, and explain why (Recommended)"), not pass as an abort.
373
+
374
+ **The doctests run without a runner.** Put to him with the four reviews, the maintainer chose on 14 November 2026 "Run all doctests, keep the group's results (Recommended)": the test binaries keep the selecting runner, checked against cargo's machine-readable list of the executables that it runs, and the doctests run for the whole workspace with a plain `cargo test --doc` and no runner, of whose results the plugin reports those of the crates that Nx asked for. The option he did not take was to keep the runner for doctests and harden it, by pinning terminal settings, rejecting output that the plugin does not recognise and restricting what tests print. This replaces the doctest part of his first answer and makes his answer on `should_panic` doctests moot: without a runner, rustdoc decides them as under plain cargo, and an aborting one passes. Its costs, told to him: every test run compiles and runs the doctests of every library, whose side effects and hangs reach the run, and a doctest of another crate that fails only warns.
375
+
376
+ **What the control plane decided within it**, on 14 November 2026, of which the maintainer is told ([[DES-TEST-RUN]], "Under `workspace-build`"): with the `cargo` runner the group runs `cargo test --workspace --no-run`, which compiles what plain `cargo test` compiles, examples without `test = true` included; then the test binaries with `--tests`, the selection that plain `cargo test` runs besides doctests, and cargo's JSON messages; then the doctests. A task passes the test binaries' step only where every test executable that cargo's messages name for its crate has a record that ends with the status 0, and nothing that cargo writes for people or a test writes decides it. Every artifact message of that command counts, with no stopping point, because a proc macro can write a forged `build-finished` line into the stream while it is compiled; a forged artifact line can then only fail a good run, which is accepted. nextest runs under the repository's configuration as plain `cargo nextest run` does, its `default-filter` included, without a profile of the plugin's own and without `--ignore-default-filter`. The runner is a Node script on Linux and macOS alike, because it passes cargo's environment on exactly, where bash as `/bin/sh` rewrote `SHELLOPTS` and `BASHOPTS`, at about 15 to 30 ms for each test binary of the workspace ([[EVD-TEST-STEPS-SPLIT]]). The maintainer confirmed that choice on 14 November 2026: "Node on Linux and macOS (Recommended)"; `/bin/sh` on Linux with Node on macOS was the option not taken. nextest needs no runner. Where a runner for the host is or may be configured, the group's tests run one crate per command, because the plugin cannot show that it reads the user's runner as cargo does ("A runner the user configured"). The `cargo` strategy passes `-Zfeature-unification` on the command line, so that stable cargo fails instead of narrowing the features ([[DES-UNIFICATION]]).
377
+ :::
378
+
379
+ :::mara decision ADR-ARTIFACT-TARGET-NAMES
380
+ :mid: 01M78FHG7FYRNEHZNVW6V2DWJ0
381
+ :title: Give each kind of artifact its own target name
382
+ :status: accepted
383
+ :justifies: REQ-ARTIFACT-TARGETS
384
+ :justifies: DES-ARTIFACT-STEPS
385
+
386
+ A different kind of artifact gets its own target name (`napi-build`, `wasm-build`); a different flavour of the same artifact is a flag. One `build` target with a configuration per artifact was rejected for four reasons. Nx's `dependsOn` names a target and cannot pin a configuration of it ([[EVD-NX-24-INSPECTION]]), so a JS app could not depend on the wasm build. `nx run-many -t build -c wasm` would run the default native build on every crate without a wasm configuration. One configuration applies per invocation, so native plus wasm would take two commands. And a named target exists only on crates that produce that artifact.
387
+ :::
388
+
389
+ :::mara decision ADR-NO-WASM-PACK
390
+ :mid: 01M78FHG7F6KP7TGK6B0447FHY
391
+ :title: Call cargo and the wasm-bindgen CLI directly
392
+ :status: accepted
393
+ :justifies: DES-WASM
394
+
395
+ wasm-pack is not a base to build on: the rustwasm organisation was sunset in 2025 and wasm-pack was slated for archiving. The plugin runs `cargo build` and the `wasm-bindgen` CLI itself, which also lets the compile step take part in batching.
396
+ :::
397
+
398
+ :::mara decision ADR-SINGLE-MACHINE
399
+ :mid: 01M78FHG7FYYRPH4D9BRH2Y94M
400
+ :title: Target a single machine in v1
401
+ :status: accepted
402
+ :justifies: DES-TEST-PHASES
403
+
404
+ Spreading Rust tasks across Nx agents needs answers that are not available yet: where Nx computes hashes, whether targets can be pinned to one machine, and how batched tasks are assigned to agents. v1 runs all Rust tasks of a pipeline on one machine. The only v1 requirement for a later distributed mode is a seam: the test executor keeps building and running as separate internal phases.
405
+ :::
406
+
407
+ :::mara decision ADR-COMPATIBILITY
408
+ :mid: 01M78FHG7FFBVZPZCQKJNXGT0P
409
+ :title: Support Nx 24, Cargo 1.91+, Linux and macOS
410
+ :status: accepted
411
+ :justifies: REQ-COMPATIBILITY
412
+ :justifies: DES-BUILD-DIRS
413
+ :accepts: RISK-UPSTREAM-CHANGES
414
+
415
+ Nx 24 makes task-based affected the default, which the cache design relies on. The plugin supports the Nx majors its end-to-end suite has passed on, which is Nx 24 at first. The batch executor interface and the way Nx evaluates inputs are not stable across majors ([[RISK-UPSTREAM-CHANGES]]), so a later major joins the package's peer dependency range only once the suite passes on it. Promising "Nx 24 and later" was rejected, because it would claim behaviour nobody has checked. Cargo 1.91 is the first version with a separate build directory, so there is one cache model and no degraded mode for older toolchains. Windows hosts need their own handling of paths, shells and linkers and are left out of v1. A repository with an older Nx or Cargo gets a clear error.
416
+ :::
417
+
418
+ :::mara decision ADR-V1-SCOPE
419
+ :mid: 01M78FHG7FTPVXE53KP8PW9NR7
420
+ :title: Limit what v1 does
421
+ :status: accepted
422
+ :justifies: REQ-NO-MANIFEST-WRITES
423
+ :justifies: REQ-DIAGNOSTICS
424
+ :justifies: REQ-COMPATIBILITY
425
+ :accepts: RISK-UNDECLARED-INPUTS
426
+ :accepts: RISK-HOST-ENVIRONMENT
427
+
428
+ The plugin stays a thin layer between Nx and Cargo. It does not install toolchains or tools: rustup, nextest, cargo-affected, cargo-hakari and the `wasm-bindgen` CLI are the user's to install, and the plugin reports what is missing. It does not build hermetically: there is no sandbox and no remote execution, and it trusts Cargo and a declared set of inputs. It does not write `Cargo.toml`, `Cargo.lock` or `.cargo/config.toml` outside generators, release and tasks the user runs to change them. It does not run on Windows hosts.
429
+
430
+ Also outside v1: cross-compiling Node addons to other platforms, wasm tests, publishing napi and wasm packages to npm, tests on triples other than the host, migration from `@monodon/rust`, formatting Rust through `nx format` ([[EVD-NX-FORMAT]]), and distributed execution ([[ADR-SINGLE-MACHINE]]). Adding any of these needs a recorded need and decision first.
431
+ :::
432
+
433
+ :::mara decision ADR-SETUP-GENERATORS
434
+ :mid: 01M78FHG7FYKPH14862MWJ4KJB
435
+ :title: Ship init and crate generators in v1
436
+ :status: accepted
437
+ :justifies: REQ-INIT
438
+ :justifies: REQ-CRATE-GENERATORS
439
+
440
+ v1 has an `init` generator behind `nx add`, and `library` and `binary` generators that wrap `cargo new`. Because projects are inferred, generators are a convenience: a crate created with plain `cargo new` works the same. A generator that migrates a repository from `@monodon/rust` is left for later.
441
+ :::
442
+
443
+ :::mara decision ADR-WORKSPACE-ROOT
444
+ :mid: 01M78NVF8ENATA4CGDH3PMYVSF
445
+ :title: Run cargo in the workspace root and key the toolchain found there
446
+ :status: accepted
447
+ :justifies: DES-INVOCATION
448
+ :justifies: DES-INPUTS
449
+ :justifies: REQ-TOOLCHAIN-KEY
450
+
451
+ rustup picks the toolchain file, and Cargo its configuration files, from the folder a command starts in and its parents, not from the manifest of the crate being built. A command for a group of crates has one such folder. The plugin therefore starts every cargo command in the workspace root, so the toolchain file and configuration files found from the workspace root apply to every task ([[TERM-WORKSPACE-CONTEXT]]). A task's environment can still override the toolchain file, as `RUSTUP_TOOLCHAIN` in a crate's `.env` does, and the toolchain input is evaluated with that environment ([[EVD-NX-24-INPUT-SEMANTICS]]). Starting each task in its crate's folder was rejected: per-crate files would apply as they do for a developer who works in that folder, but crates with such files could not share an invocation.
452
+
453
+ The first design keyed the toolchain with `rustup run <channel> rustc -Vv`, with the channel read from the toolchain file. That needs rustup, and it misses a toolchain chosen through `RUSTUP_TOOLCHAIN` or `rustup override`, which cargo honours. Plain `rustc -Vv`, run in the workspace root, asks the question cargo will ask, with or without rustup, as long as no setting names another compiler. `RUSTC`, `CARGO_BUILD_RUSTC` and `build.rustc` do, and cargo then runs that compiler, so the command also asks the one they name, while `rustc -Vv` still names the toolchain of the task's cargo ([[EVD-CARGO-COMPILER-SELECTION]]).
454
+
455
+ The cost is that a toolchain or configuration file inside a member crate changes the cache key without changing what Nx runs, and that a developer who starts cargo inside such a crate builds differently from Nx. The documentation says so. Nx 24 runs a runtime input through `sh -c` in the repository root, so the toolchain command can change into the workspace root first ([[EVD-NX-24-INPUT-SEMANTICS]]).
456
+ :::
457
+
458
+ :::mara decision ADR-CI-LINUX-ONLY
459
+ :mid: 01M78KFR0QP1XDDHMYRA2RTNET
460
+ :title: Run CI on Linux only for the moment
461
+ :status: accepted
462
+ :accepts: RISK-MACOS-UNVERIFIED
463
+ :accepts: RISK-TERMINAL-ENVIRONMENT-MACOS
464
+
465
+ GitHub's hosted macOS runners are in short supply in November 2026, so jobs on them wait long or do not start. The plugin is a JavaScript package with no platform-specific build, so only test runs are affected: this repository's CI runs its unit and end-to-end tests on Linux only for the moment. macOS stays a supported host ([[ADR-COMPATIBILITY]]), and code must not assume Linux. What is deferred is the check: no macOS run backs the claim until the jobs are added, and [[VER-SETUP]] says so. When macOS runners are usable again, the macOS jobs are added to the workflow, the macOS part of the verification is restored, and this decision and its risk are retired.
466
+ :::
467
+
468
+ :::mara decision ADR-PUBLISHING-AT-1-0
469
+ :mid: 01M7D7W01MEC0ER974G0K2G8M1
470
+ :title: Complete the milestones on main and decide on publishing at 1.0
471
+ :status: accepted
472
+
473
+ The maintainer's decision of 14 November 2026. The milestones of the [roadmap](product.mara.md#roadmap) are completed on `main` one after another, and no 0.x milestone is published to npm on its own: whether and when `@convesoft/nx-rust` is published is decided at 1.0. A 0.x milestone is complete when its own checks pass on `main`, and publishing is not one of them; whether publishing is a check of 1.0 is part of what is decided there. Until a version is published, `nx add @convesoft/nx-rust` cannot install the plugin, and the status notes say so. Publishing each 0.x milestone once it is complete, as the milestones were first planned, was rejected.
474
+
475
+ Amended by the maintainer on 21 November 2026: `@convesoft/nx-rust` uses its own independent semantic versioning (rather than matching Nx's major version, since private Nx internals can change in minor releases while one plugin version can span multiple Nx majors; [[REQ-COMPATIBILITY]]). Ahead of `1.0.0`, 1.0 release candidates (starting with `1.0.0-rc.1`) may be published to npm through `.github/workflows/release.yml` via npm Trusted Publishing (OIDC, bound to the `npm` GitHub Environment) so real-repository validation ([[VAL-MIXED-REPO]], [[VAL-CARGO-PARITY]], [[VAL-CACHE-TRUST]]) can install the plugin from npm.
476
+ :::
477
+
478
+ :::mara decision ADR-BUNDLED-DOCS
479
+ :mid: 01M81H7N75PJEZC7XE5B1Z4JTR
480
+ :title: Ship PLUGIN.md and the docs folder in the npm package
481
+ :status: accepted
482
+
483
+ The maintainer's decision of 22 November 2026. The published `@convesoft/nx-rust` package carries `PLUGIN.md` at its root and every file of `nx-rust/docs/` as it is, in a `docs/` folder beside it, so that coding agents and developers in an adopting repository read, through `node_modules/@convesoft/nx-rust/`, the documentation of the version they have installed rather than that of `main`. `PLUGIN.md` is a short guide for agents: it summarises the common commands, the `Cargo.toml` tables and the caching rules and points into `docs/`, whose items stay the normative text. Linking only to the documentation on GitHub, as the README did, was the alternative; it describes `main`, which can be ahead of or behind a published release ([[ADR-PUBLISHING-AT-1-0]]).
484
+
485
+ `PLUGIN.md` sits at the package root because that is the path Nx 24 names. In the `nx` 24.0.6 package that this repository installs, `dist/src/ai/set-up-ai-agents/get-agent-rules.js` writes into the agent rules it generates: "For Nx plugin best practices, check `node_modules/@nx/<plugin>/PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable." The rule names only `@nx/*` plugins, sets no format, and no code of `nx` reads the file. Of the `@nx/*` 24.0.6 plugins installed here, only `@nx/jest` ships one, at `dist/PLUGIN.md`, not at the path that the rule names; its sections (detection, commands, a quick reference) are the shape that the plugin's `PLUGIN.md` follows. Read on 22 November 2026, not run.
486
+
487
+ The build copies the folder whole, so a new page ships without a change to the build. `PLUGIN.md` links into `docs/` with paths relative to the package root, which resolve both in the repository, where `nx-rust/` holds both, and in the installed package.
488
+
489
+ Two consequences are accepted. The pages ship as they are, so a relative link that leaves `docs/`, such as the links to `.zban/` in the documentation index and in the product page, does not resolve inside the package. And the package grows by the size of the pages, about 1.9 MB unpacked when this was decided, of which this page is about 0.77 MB, some 40%.
490
+ :::
491
+
492
+ :::mara decision ADR-UNKNOWN-OPTIONS
493
+ :mid: 01M7A93PSWEZZPRGCDQCJ8DHE4
494
+ :title: Run tasks without options the executor does not know and say so in their output
495
+ :status: accepted
496
+ :justifies: REQ-UNKNOWN-OPTIONS
497
+ :justifies: REQ-UNKNOWN-METADATA-OPTIONS
498
+ :justifies: DES-UNKNOWN-OPTIONS
499
+
500
+ Rust targets share their names with JS targets ([[ADR-NX-TARGET-NAMES]]), so options written for JS executors reach the plugin's executors: from a `targetDefaults` entry such as `test: { options: { passWithNoTests: true } }`, from a `project.json` or `package.json`, and from flags such as `--coverage` on `nx affected -t test`, which Nx passes to every task of the target ([[EVD-NX-OPTION-VALIDATION]]). On 13 November 2026 the maintainer chose to run such a task as if the option were absent and to say so in the task's own output when it starts. Two reviews then found cases in which the plugin named a source that had not supplied the option. He decided on the same day that the line says the option was passed on the command line only when it is among the command's own flags, and otherwise that it comes from the workspace's configuration, naming the command that shows exactly where and the two fixes for a `targetDefaults` entry.
501
+
502
+ Rejected:
503
+
504
+ - **A closed schema** (`additionalProperties: false`). Nx then fails every task that it hands to the batch implementation, those without the option too, with an unhandled `SchemaError` that names neither the option nor a task, and `--verbose` adds nothing. That breaks [[REQ-BATCHING]], under which a task fails only for its own crate.
505
+ - **Failing the task**, with a clear message from the executor. Settings that mixed repositories use routinely would stop Rust tasks until every entry and flag was narrowed, although such an option changes nothing that cargo does.
506
+ - **Ignoring the option silently.** A misspelt option, or one the user expects to have an effect, would go unnoticed ([[NEED-CLEAR-FAILURES]]).
507
+ - **Reporting at graph creation.** As an error it stops every Nx command of the repository, JS ones included ([[REQ-DIAGNOSTICS]]). As a warning it reaches only the daemon's log on a developer machine. A flag on the command line is not in the graph at all.
508
+ - **Naming the file or the `targetDefaults` key** that gave the option. Two reviews found cases in which a reconstruction of Nx's merge from the executor's context named a source that had not supplied the option ([[EVD-NX-OPTION-VALIDATION]]). Nx records the source in its own source map, which `nx show target` shows, and the line names that command instead.
509
+
510
+ Ignoring is safe for the cache: Nx keeps the option in the task's key, so a run with another value runs again instead of restoring a result made without it ([[GOAL-TRUSTED-CACHE]]). The costs are that a misspelt Rust option set through a target default or a flag only warns, and that the warning repeats on every run until the entry is narrowed. A declared option with a value of the wrong type still fails every task that Nx hands to the batch implementation with it, with Nx's message, because the option types stay in the schema for Nx's conversion of command-line values.
511
+
512
+ The plugin's own tables in Cargo manifests are treated differently. The plugin owns that source and knows at graph creation which options its executors have, so an unknown key under a target's `options` or one of its configurations there fails graph creation, the earliest point at which the mistake is known, and names the manifest, the target, the configuration if any, and the key ([[REQ-DIAGNOSTICS]]).
513
+ :::
514
+
515
+ :::mara decision ADR-NO-ERROR-CODES
516
+ :mid: 01M7A67WRX56A7M56CJZ7VF326
517
+ :title: Name problems in words, without error codes, in v1
518
+ :status: accepted
519
+ :justifies: DES-DIAGNOSTICS
520
+
521
+ A diagnostic says what is wrong, where, and what to do ([[REQ-DIAGNOSTICS]]). In v1 it carries no code. Nx 24 shows no numbered codes in its diagnostics, and the cargo messages seen while designing the generators carried none either ([[EVD-NX-24-SETUP]], [[EVD-CARGO-NEW]]), so a code would stand alone in a user's output. Once published, a code is an interface to keep stable and to document. Tests check the facts a message names instead.
522
+
523
+ Codes may be introduced later without breaking anything, because adding a code to a message takes away nothing a user or a script relies on. They would serve people or tools that need to refer to one problem across releases: a documentation page per problem, filtering warnings in a pipeline, or wording that changes often. One possible scheme is a stable code for each row of [[DES-DIAGNOSTICS]], listed in the setup guidance and never reused for another problem. Whether to introduce codes, and in what form, is decided when such a need arises.
524
+ :::
525
+
526
+ :::mara decision ADR-DECLARED-FILE-INPUTS
527
+ :mid: 01M7ACMK1QTQXRJFFNXHPB53FS
528
+ :title: Declare files outside a crate instead of learning them from builds
529
+ :status: accepted
530
+ :justifies: REQ-BUILD-SCRIPT-INPUTS
531
+ :justifies: REQ-FILE-INPUTS-HASHABLE
532
+ :justifies: REQ-BUILD-INPUT-CHECK
533
+ :justifies: DES-INPUTS
534
+ :justifies: DES-BUILD-INPUT-CHECK
535
+
536
+ A build script, a macro or a test can read files outside its crate's folder, which the crate-file input does not cover. The cache key has to name such files before the task runs, and nothing reports them then: neither the `cargo metadata` report nor Cargo's JSON messages carry them ([[EVD-CARGO-NO-DEPS]], [[EVD-CARGO-DEP-INFO]]). Only Cargo's records of a finished build do. The repository therefore declares these files in its Cargo manifests under `fileInputs`, and the plugin turns each pattern into an Nx fileset. The key is named to pair with the keys that add environment variables and commands to the key.
537
+
538
+ Three alternatives were rejected:
539
+
540
+ - **Learning the paths from earlier builds.** Only `cargo build` leaves a documented record, the dependency file beside each artifact. The records of `check`, `lint`, `test` and `doc` exist only in the build directory, whose layout moved between Cargo 1.97 and 1.100 and which the plugin never reads ([[DES-BUILD-DIRS]]). Records exist per machine and only after a build, so a fresh CI checkout has none: its first run would either compute a key without the files, which a shared cache could later answer with a result built from other files, or a key that never hits. Carried in a runtime input, the learned files would change keys but never make a task affected, because task-based affected matches changed files against declared file inputs only ([[ADR-DECLARED-INPUTS]], [[EVD-NX-24-INPUT-SEMANTICS]], [[EVD-NX-24-FILE-INPUTS]]).
541
+ - **Scanning `build.rs` and the sources for literal paths.** Build helpers such as tauri-build and bindgen print `rerun-if-changed` for paths they compute, and a proc macro can open files itself ([[EVD-CARGO-DEP-INFO]]). A scan would find a part and suggest it found all.
542
+ - **Leaving the files out of v1.** A runtime command under `runtimeInputs` that hashes the files changes keys, but `nx affected` ignores it. A change to a shared protocol definition would then leave `nx affected -t build` green without building the crates that embed it, which [[NEED-AFFECTED]] rules out.
543
+
544
+ A declaration also covers what no record shows: a file that a proc macro opens by itself, which Cargo does not track either. Its cost is that the repository has to state the files. To catch what it forgot, a `build` task that ran cargo compares the dependency files Cargo wrote with its inputs, and fails when one names a repository file that no input covers ([[REQ-BUILD-INPUT-CHECK]]). It fails instead of warning because Nx stores every successful result and an executor cannot report success without it being stored, so a warning would leave a result under a key known to miss a file ([[EVD-NX-24-FILE-INPUTS]]). Nx Cloud can record the files a task reads, but nothing records them without it, so that is no substitute.
545
+
546
+ Nx matches a declared pattern only against the files of the project whose folder holds the folder where the pattern starts, and leaves out the projects in folders below it ([[EVD-NX-24-FILESET-SCOPE]]), so a pattern written to cover the crates beside a crate, such as `../*/src/**`, would miss them. A declared pattern is never left out of the key without a word: the plugin turns it into filesets that Nx matches, one for each folder of its own projects below where the pattern starts, and fails graph creation where it reaches the folder of a project that another plugin or entry creates, which it cannot see when it creates its own. Leaving such files out with a warning, or documenting the limit, was rejected, because the key would still miss files that the repository declared ([[GOAL-TRUSTED-CACHE]]). More files in a key than the pattern names are acceptable; fewer are not. The two decisions therefore err on different sides. Adding filesets errs towards more: where the plugin cannot tell whether a segment matches a folder, it adds the folder. Failing graph creation must not fail a pattern that works: the plugin reads the pattern as Nx does, each alternative of braces as a pattern of its own and each segment matched with Nx's own glob matching, and fails only for a folder that the pattern reaches; only a construct that it cannot evaluate keeps the error, whose pattern still works when added. A pattern that names a folder, by a trailing `/` or by a name at its end, counts everything below it, also where it has a glob and Nx alone would count files only, as Nx counts a path without a glob.
547
+ :::
548
+
549
+ :::mara decision ADR-GRAPH-NO-TOOLCHAIN-INSTALL
550
+ :mid: 01M7AN094P6S3K7M62DNC8P15H
551
+ :title: Let rustup install no toolchain while the graph or a cache key is computed
552
+ :status: accepted
553
+ :justifies: DES-METADATA-REPORT
554
+ :justifies: DES-INPUTS
555
+ :justifies: DES-DIAGNOSTICS
556
+
557
+ A workspace's `rust-toolchain.toml` can pin a toolchain that the machine lacks, and rustup installs such a toolchain the first time a command needs it, unless `RUSTUP_AUTO_INSTALL=0` is set ([[EVD-RUSTUP-MISSING-TOOLCHAIN]]). The plugin runs cargo whenever Nx creates the project graph, also on a machine that only works on JS projects. It therefore runs every cargo command of graph creation with `RUSTUP_AUTO_INSTALL=0`: a pinned toolchain that is missing fails graph creation with rustup's message, which names it, and creating the graph downloads nothing ([[ADR-V1-SCOPE]]). Where cargo is no rustup proxy, the variable has no effect. The cargo commands of tasks get no such setting, so a task installs a missing toolchain exactly when the same plain cargo command would ([[REQ-CARGO-UNCHANGED]]).
558
+
559
+ The toolchain input of a task's key runs `rustc -Vv`, and the version query of a compiler or rustdoc that a setting names, with the variable as well. Nx 24.0.6 cannot fail a task from a runtime input: it keys the task on what the command prints and runs it ([[EVD-RUSTUP-MISSING-TOOLCHAIN]]). When the toolchain is missing, the input therefore yields a value that never repeats, so that no result stored under that key can be restored, and the task runs as plain cargo does. The message that names the toolchain comes from graph creation, which fails first in nearly every case.
560
+
561
+ Leaving rustup's default was rejected, because `nx graph`, or any Nx command that creates the graph or computes a key, could then download a toolchain unasked. Setting the variable for tasks as well, or failing a task from the executor when its toolchain is missing, was rejected, because a task would then fail where the same plain cargo command succeeds. Keying the task on rustup's message was rejected, because the message names a channel such as `stable` and not the release that cargo would install, so a result could be restored for another toolchain.
562
+ :::
563
+
564
+ :::mara decision ADR-REDIRECTION-EDGES
565
+ :mid: 01M7AQ58FTSJX0AWN2BGZF4TND
566
+ :title: Give the crates that [patch], [replace] and paths redirect to edges from every member that may use them
567
+ :status: accepted
568
+ :justifies: REQ-DEPENDENCY-EDGES
569
+ :justifies: DES-PROJECT-GRAPH
570
+ :justifies: DES-METADATA-REPORT
571
+ :justifies: DES-INPUTS
572
+ :justifies: DES-DISCOVERY
573
+ :justifies: DES-DIAGNOSTICS
574
+ :justifies: REQ-INPUT-FILES
575
+
576
+ Agreed with the maintainer on 13 November 2026. Through `[patch]`, `[replace]` and `paths`, cargo builds a local crate in place of a registry or git dependency, and the graph's `--no-deps` report shows none of them. Without more, a crate that cargo builds against another crate of the repository this way has no edge to it, and neither `nx affected` nor its cache keys follow that crate ([[EVD-CARGO-REDIRECTIONS]], [[GOAL-TRUSTED-CACHE]]).
577
+
578
+ The plugin therefore reads the tables from files when it creates the graph: `[patch]` and `[replace]` from each workspace's root manifest, and `[patch]` and `paths` from the configuration files that cargo reads for the workspace's tasks. That needs no cargo call, no network and no `Cargo.lock`. It is the one place where the plugin parses Cargo's files itself, and it makes a TOML parser a dependency of the plugin.
579
+
580
+ The files say neither whether cargo uses a redirected crate nor which crates reach it, through a registry crate or through a path crate of another workspace. Every member with a registry or git dependency, of its own or of a path crate it reaches, therefore gets an edge to every redirected crate with a project but itself. That is a superset: no edge is missing, so keys and `nx affected` are right, and the graph may show edges that cargo does not have.
581
+
582
+ Where the redirected crate reaches the member through normal or build dependencies, cargo would reject the member's use of it as a cycle, so only the member's dev-dependencies can lead there. The edge would close a cycle that cargo never has, which a user's `dependsOn: ["^build"]` turns into a task cycle that fails the run ([[EVD-NX-24-INSPECTION]]). That edge is left out, and the member's targets get the redirected crate's files as an input instead. Where the redirected crate reaches the member only through a dev-dependency, the edge stays, as [[ADR-ALL-DEP-KINDS]] keeps such cycles.
583
+
584
+ The review of the change refined this on 13 November 2026, without changing the answers above: a dependency whose name, source and version requirement a redirected crate satisfies is resolved to it by cargo, so that edge is real and always kept, and it counts among the real dependencies that leave a possible edge out. A requirement that the redirected crate does not satisfy is no redirection. Two redirected crates that may only possibly use each other get no edge either way, but each other's files as an input, because cargo can have at most one direction and the plugin cannot tell which ([[DES-PROJECT-GRAPH]]).
585
+
586
+ A configuration file outside the repository, such as the Cargo home's, applies like one inside it, and the plugin warns that Nx does not see changes to it. On 14 November 2026 the control plane of the work decided, as the consistent extension of that warning, that it covers every file whose redirections the plugin follows and whose changes Nx does not see: also a configuration file or root manifest inside the repository that an ignore rule, such as one in `.gitignore` or `.nxignore`, leaves out of the files that Nx reads, for which the Nx daemon does not create the graph again either ([[EVD-CARGO-REDIRECTIONS]]). Its remedy is to stop ignoring the file or to run `nx reset` after changing it. Later that day the warning became part of the one for every Cargo configuration file that Nx does not hash ([[RISK-HOST-ENVIRONMENT]], [[DES-DIAGNOSTICS]]), which no key holds and which every task of the workspace's projects prints; for a file with redirections it adds that the graph's edges follow a change only once Nx creates the graph again.
587
+
588
+ Rejected: edges only from the members that declare the redirected crate's name, which miss the uses through registry crates and through other workspaces' crates; a resolved `cargo metadata` report, which needs the network or a filled Cargo home and writes `Cargo.lock`, or with `--locked` fails while it is stale ([[ADR-METADATA-NO-DEPS]]); reading `Cargo.lock` while the graph is created, which still needs the tables for the crates' folders, holds no trace of `paths` and needs the superset whenever the lockfile is stale; a warning or an error in place of edges; and inputs in place of edges, which neither the `^` inputs of the member's dependents nor the project graph follow.
589
+ :::
590
+
591
+ :::mara decision ADR-SKIP-VENDORED-CRATES
592
+ :mid: 01M7AXAXTJ5B3ZF3AQ7X1BXVSE
593
+ :title: Skip the crates whose folder holds cargo's .cargo-checksum.json, unless they are members
594
+ :status: accepted
595
+ :justifies: DES-DISCOVERY
596
+ :justifies: DES-METADATA-REPORT
597
+ :justifies: REQ-SKIP-CRATES
598
+
599
+ Settled on 13 November 2026 under the maintainer's standing instruction to settle what follows from decisions already taken, as a consequence of [[ADR-CARGO-SOURCE-OF-TRUTH]]. `cargo vendor` writes the packages of a registry or git source into a folder, and Nx hands every `Cargo.toml` there to the plugin. Inside a workspace's folder `cargo metadata` fails for each of them, which failed graph creation; outside every workspace's folder each became a standalone crate with a project ([[EVD-CARGO-REDIRECTIONS]]).
600
+
601
+ A crate whose folder holds `.cargo-checksum.json` beside its `Cargo.toml` is a package of a directory source: `cargo vendor` writes that file for every crate it vendors, and cargo refuses a directory-source package without it ([[EVD-CARGO-REDIRECTIONS]]). The plugin reads no such manifest, so the crate gets no project, no edge and no cargo call of its own, wherever its folder lies, whichever plugin entry receives the manifest and whatever Cargo's configuration says. A crate that a workspace's report lists among its members, as cargo enrols one that a member depends on by path, is a member like any other and gets its project. A path dependency on such a crate that is no member is a path dependency without a project, whose folder is an input of the crates that use it, but the plugin requests no report for it. Cargo checks a vendored crate's files against that file, and `Cargo.lock` holds its checksum, which the lockfile digests cover ([[DES-LOCKFILE-HASHING]]). `exclude` on the plugin's entry and `.nxignore` stay the way to keep Nx from handing the files over at all.
602
+
603
+ The rule settled first skipped every manifest in a folder that a `[source.<name>]` table's `directory` names in the configuration files that cargo reads for a workspace. The review dropped it the same day, because a folder named in configuration is the wrong evidence: with `directory = "../shared"` in the configuration of a workspace whose member depends by path on a member of the workspace in `shared/`, the graph lost both crates of `shared/` and the edge between the members, while cargo still built the dependency by path ([[EVD-CARGO-REDIRECTIONS]]). A plugin entry that received only the vendor folder never saw the configuration that named it, and still failed.
604
+
605
+ Rejected as well: documenting `exclude` only, which leaves a repository that commits its vendored sources with a failing graph until the user finds the option; recognising a vendor folder by its name; and reading the vendored crates and dropping the failures, which costs one cargo call for each of hundreds of crates and still gives the crates outside every workspace's folder projects.
606
+ :::
607
+
608
+ :::mara decision ADR-TRIPLE-OUTPUTS
609
+ :mid: 01M7BGFY4YPWXVSM78SMPJJV3Y
610
+ :title: Declare build and doc outputs in the folders of the triples that Cargo's configuration or environment picks
611
+ :status: accepted
612
+ :justifies: DES-OUTPUTS
613
+ :justifies: DES-INPUTS
614
+
615
+ Agreed with the maintainer on 13 November 2026, who chose "Follow cargo: cache with the right folder". Without `--target`, cargo builds for the triples that `build.target` in its configuration and `CARGO_BUILD_TARGET` pick, and puts their artifacts and documentation into each triple's folder of the artifact directory, also for the host's own triple ([[EVD-CARGO-TRIPLE-FOLDERS]]). Outputs that ignored those settings would name folders that cargo does not write to, and a cached success would restore no artifact ([[GOAL-TRUSTED-CACHE]]). Since caching landed, the plugin therefore left `build` and `doc` uncached where the configuration sets `build.target`, and failed a cached one whose triple `CARGO_BUILD_TARGET` picks.
616
+
617
+ The plugin now reads the triples that the configuration and the environment pick, as cargo does, and declares the outputs of `build` and `doc` in each one's folder, a list of triples in each triple's folder, so that both stay cached ([[DES-OUTPUTS]]). Cargo has no stable command that reports them, so the plugin merges the configuration files itself, in cargo's order ([[EVD-CARGO-TRIPLE-FOLDERS]]).
618
+
619
+ Two limits follow from the principle that nothing is cached that the plugin cannot name. Outputs are fixed when Nx creates the graph, so a triple that only a task's environment picks, such as through a dotenv file of the crate, fails a cached task before cargo runs. And where the plugin cannot name the folder at all, as for `host-tuple` or a file that only `include` adds, `build` and `doc` stay uncached unless their options name a triple.
620
+
621
+ Agreed with the maintainer on 14 November 2026, after a review found that the Nx daemon keeps outputs that name the old triple when a configuration file outside the repository changes, and that the key did not change with it: the key of a cached `build` and `doc` follows the triples that cargo will use when the task runs, through a runtime input that resolves them with the same function, whatever the daemon's graph holds; the executor then fails such a task before cargo runs and says to run `nx reset` ([[DES-INPUTS]], [[EVD-CARGO-TRIPLE-FOLDERS]]). The executor compares with the graph's outputs and not with what the runtime input printed for the key, so a change of the configuration or of the task's environment made while a command is running, between the computing of a task's key and the start of the task, is outside what it sees, as for every input of a key ([[DES-OUTPUTS]], "Keys").
622
+
623
+ The `targetTriple` option, by the control plane's decision of 14 November 2026 under [[GOAL-TRUSTED-CACHE]], which applies the rule that the maintainer was told that day, and did not object to, as closely as an option allows: a cached `build` or `doc` whose option is `host-tuple` or a target specification file fails before cargo runs, and its message says to pass the host's triple, which it names, in place of `host-tuple`, or for a specification file to build with a built-in triple or uncached ([[DES-OUTPUTS]]). Where Cargo's configuration picks such a value, graph creation leaves the targets uncached; an option arrives with the task, when Nx has decided to cache it already.
624
+
625
+ Rejected: rejecting `build.target` and `CARGO_BUILD_TARGET` for cached targets, the interim rule, which leaves every repository that configures a triple without cached builds or makes it repeat the triple as an option; caching only what the `targetTriple` option names; and naming the host's folder for a `host-tuple` option, which no output can do, because Nx puts the option's text into the outputs.
626
+ :::
627
+
628
+ :::mara decision ADR-ARTIFACT-DIR-OUTPUTS
629
+ :mid: 01M7CKYHWJVN634GVV0818HP11
630
+ :title: Fail a cached build or doc whose artifact directory is not the one its outputs name
631
+ :status: accepted
632
+ :justifies: DES-OUTPUTS
633
+ :justifies: DES-INPUTS
634
+ :justifies: DES-BUILD-INPUT-CHECK
635
+
636
+ The control plane's decision of 14 November 2026 under [[GOAL-TRUSTED-CACHE]], which applies to the artifact directory the rule for the triple that the maintainer was told that day and did not object to ([[ADR-TRIPLE-OUTPUTS]]). The outputs of `build` and `doc` name the artifact directory of graph creation's report, but cargo can write elsewhere when the task runs: under the Nx daemon after a change to a configuration file outside the repository, and wherever a dotenv file that Nx loads only for the task sets `CARGO_TARGET_DIR`, `CARGO_BUILD_TARGET_DIR` or `CARGO_HOME`. Both were reproduced with Nx 24.0.6: Nx stored whatever lay at the declared paths under a key that did not change, and restored an older binary for a newer source ([[EVD-NX-24-MOVED-ARTIFACT-DIRS]]).
637
+
638
+ The key of a cached `build` and `doc` therefore follows the artifact directory that cargo will use, whatever the daemon's graph holds: the runtime input that prints the triples also prints the directory, in the form that the outputs name it, so that it splits no key that the outputs do not split already ([[DES-INPUTS]]). When such a task starts, the executor asks cargo for its directories with the task's environment and fails the task before cargo builds where the artifact directory is not the one that the outputs name: with the `nx reset` message where Cargo's configuration changed, and with a message that names both folders and where to set the variable instead where the task's environment moves it ([[DES-OUTPUTS]]). The check of [[DES-BUILD-INPUT-CHECK]] takes Cargo's build and artifact directories from the same report, so a `CARGO_BUILD_BUILD_DIR` that only the task's environment sets no longer fails it. The executor compares with the graph's outputs, not with the directory that the runtime input printed for the key, so a change of Cargo's configuration or of the task's environment made while a command is running, between the computing of a task's key and the start of the task, is outside what it sees, as for every input of a key; that needs the configuration to change twice during one command, and closing it would need a record written when the key is computed for the executor to compare with, which the plugin does not write ([[EVD-NX-24-MOVED-ARTIFACT-DIRS]]).
639
+
640
+ The plugin asks cargo, with `cargo metadata --no-deps`, rather than reading the configuration and the variables itself: cargo resolves every source, a file that `include` adds as each version reads it, a Cargo home that only the task's environment names, and the templates of `build.build-dir`. It costs one cargo call in each evaluation of the runtime input and one at the start of each such task that runs, about 6 ms each where cargo is the rustup proxy ([[EVD-NX-24-MOVED-ARTIFACT-DIRS]]). Tasks run as a group share their workspace and environment, so a group asks once ([[DES-BATCH]]).
641
+
642
+ Rejected: comparing only the variables, which misses a configuration file that changed under the daemon and a `build-dir` template; a warning, which leaves the wrong result in the cache; and reading the task's dotenv files when the graph is created, with Nx's internal `getGraphTimeDotEnvForTask`, so that such a folder is cached, which depends on an internal Nx API and leaves `.env.<configuration>` files unknown, because outputs belong to a target and not to a configuration.
643
+ :::
644
+
645
+ :::mara decision ADR-BATCHED-PUBLISH
646
+ :mid: 01M7DBRA91K5CG1Y1FKGKQMMC4
647
+ :title: Publish the crates of each Cargo workspace with one multi-crate cargo publish
648
+ :status: accepted
649
+ :justifies: DES-RELEASE
650
+
651
+ The maintainer's decision of 14 November 2026, with the option chosen, word for word: "One `cargo publish` per workspace (Recommended)".
652
+
653
+ Nx release orders publishing only through the `dependsOn` of the target `nx-release-publish`; `@nx/js` and `@monodon/rust` 3.0.0 give each package `^nx-release-publish` ([[EVD-NX-24-RELEASE]]). Cargo 1.91 and later publish several crates of a workspace in one call: cargo orders them, packages and verifies each against the others before it uploads any, waits for each upload to appear in the index, and stops rather than publish a crate after the wait for one it depends on has timed out. One dependent alone cannot even be packaged before its dependency's new version is in the registry ([[EVD-CARGO-PUBLISH]]).
654
+
655
+ Each crate's `nx-release-publish` therefore has no `dependsOn`. Its executor has a batch implementation with `preferBatch`, which runs one `cargo publish -p a -p b …` per Cargo workspace, and per registry since the refinement below, and leaves the order to cargo ([[DES-RELEASE]]). [[REQ-NO-RUST-TASK-DEPS]] stays as it is.
656
+
657
+ **Refinement.** On 14 November 2026, after the research on Nx's `--registry` (nxr-fwxn1r), the control plane of the work refined this decision, and the maintainer is told: the crates are grouped per Cargo workspace, release group and the registry that cargo publishes them to, with one `cargo publish` for each group, and a call runs after those whose crates its crates depend on ([[DES-RELEASE]]). One call for crates whose `publish` settings differ fails as a whole: `publish = ["alpha"]` beside `["beta"]` conflict, and a crate without a list beside one with `["alpha"]` needs a registry named for the call, while plain cargo publishes each of them alone ([[EVD-CARGO-PUBLISH-REGISTRIES]]). Where every crate of a workspace goes to one registry, the usual case, it stays one call per workspace.
658
+
659
+ Rejected: one task per crate whose `dependsOn` names the publish targets of the crates it depends on, as `@nx/js` and `@monodon/rust` do. It is the form Nx expects, with a result per task from Nx itself, but it needs an exception to [[REQ-NO-RUST-TASK-DEPS]]; `nx release publish --dry-run` fails for every dependent of a crate bumped in the same run, because cargo cannot verify the dependent against a version that is not in the registry yet; a registry whose index takes longer than cargo's 60-second wait lets cargo end the dependency's task successfully, after which the dependent's task starts and fails ([[EVD-CARGO-PUBLISH]]); and `^nx-release-publish` follows the plugin's edges, a superset of Cargo's dependencies ([[DES-PROJECT-GRAPH]]), whose cycles Nx breaks in an arbitrary direction under the `nxIgnoreCycles` that `nx release publish` sets ([[EVD-NX-24-RELEASE]]).
660
+
661
+ The costs: publishing rests on Nx's batch executor interface and on per-task results from a batch, which milestone 0.2 builds and checks ([[ADR-BATCH-EXECUTOR]], [[RISK-BATCH-BEHAVIOUR]]); the result of each crate comes from reading cargo's output; and without a batch the tasks publish one crate each in no set order, so a dependent fails before any upload, under the check that its dependencies are in the registry ([[DES-RELEASE]]), until its dependency is published. Multi-crate publishing needs Cargo 1.91, which [[ADR-COMPATIBILITY]] requires anyway: Cargo 1.89 rejects several `-p` on `cargo publish` as unstable.
662
+ :::
663
+
664
+ :::mara decision ADR-PUBLISH-REGISTRY-OPTION
665
+ :mid: 01M7DMCC1WYYNB0EBYZSH53KKT
666
+ :title: Fail a crate's publish task that receives Nx's registry option, and point to Cargo's own settings
667
+ :status: accepted
668
+ :justifies: DES-RELEASE
669
+
670
+ The maintainer's decision of 14 November 2026, with the option chosen, word for word: "Keep failing, with guidance (Recommended)".
671
+
672
+ `nx release publish --registry <value>` hands the same raw value to every publish task of the run, npm packages and crates alike, and a `registry` in a target's options or in a `targetDefaults` entry keyed by `nx-release-publish` reaches the task as well ([[EVD-NX-24-PUBLISH-OPTIONS]]). npm takes the value as a URL: given a bare name, npm 12 warned and published to the public npm registry, and pnpm 12 failed. Cargo takes the name of a configured registry with `--registry`, which refuses any value with `:` or `+`, or an index URL with `--index`, which refuses a bare name ([[EVD-CARGO-PUBLISH-REGISTRIES]]). One value cannot be right for both kinds of package.
673
+
674
+ A crate's task that receives `registry` therefore fails before cargo runs, in a dry run too, wherever the value came from, and its message says how Cargo chooses a registry by itself: `publish = ["<name>"]` in the crate's manifest, `registry.default` in Cargo's configuration, or `CARGO_REGISTRY_DEFAULT=<name>` for one run ([[DES-RELEASE]], **Options**). These work as they do with plain cargo ([[GOAL-CARGO-NATIVE]]).
675
+
676
+ Rejected:
677
+
678
+ - Treating the value as the name of a Cargo registry, passed as `--registry`. It moves the crates of a call but not what their path dependencies point to: an entry without a `registry` key stays crates.io's in the published crate, whatever the call publishes to and whatever the configuration puts in place of crates.io, so a crate either fails to package or is uploaded to the named registry depending on crates.io's crate of that name ([[EVD-CARGO-PUBLISH-REGISTRIES]]). A workspace that can publish elsewhere names the registry in those entries already, and there `publish = ["<name>"]` chooses it without a flag. A mixed run with a name would also send the npm packages to the public npm registry.
679
+ - Accepting a name or a URL, told apart by the form, and passing a URL as `--index`. A real upload through `--index` needs `--token`, whatever credentials Cargo has for that registry, and the plugin passes no token ([[DES-RELEASE]], **Credentials and tree**); `--index` ignores a crate's `publish` list, and uploaded a crate that allows one registry only into another; and an npm URL is no Cargo index: without `sparse+`, cargo fetches it as a git index and fails ([[EVD-CARGO-PUBLISH-REGISTRIES]]).
680
+
681
+ The costs: choosing a registry for one run takes an environment variable instead of a flag, and a repository that gives its npm packages a registry on the command line publishes them in a run of their own, as it would have to with any mapping. The decision can be reversed: accepting registry names later breaks no one.
682
+ :::
683
+
684
+ :::mara decision ADR-PUBLISH-REPLACED-CRATES-IO
685
+ :mid: 01M7DS8KTYRE7ND0ZYRGPMFPTS
686
+ :title: Fail a crate for crates.io where the Cargo configuration replaces crates.io
687
+ :status: accepted
688
+ :justifies: DES-RELEASE
689
+
690
+ The maintainer's decision of 14 November 2026, with the option chosen, word for word: "Keep failing, with guidance (Recommended)".
691
+
692
+ On a machine whose Cargo configuration replaces crates.io, as with a mirror, plain `cargo publish` refuses a crate without a `publish` list unless it gets `--registry crates-io`, which goes to crates.io itself past the replacement, and a `publish = ["crates-io"]` list or `CARGO_REGISTRY_DEFAULT=crates-io` sends it there in the same way. The lookup that the plugin runs on crates.io, `cargo info --index sparse+https://index.crates.io/`, asks the replacement instead, and no lookup that asks crates.io itself there is known ([[EVD-CARGO-PUBLISH-REGISTRIES]]), so the plugin cannot establish that its lookups asked the registry that the upload goes to (**Registries** in [[DES-RELEASE]]).
693
+
694
+ Such a crate therefore fails before `cargo publish` runs, with each crate that depends on it, and its message says to publish it from a job whose Cargo configuration does not replace crates.io.
695
+
696
+ Rejected: passing `--registry crates-io`, which would upload to crates.io while the checks before the upload had looked versions up in the replacement.
697
+
698
+ The cost: a repository whose machines replace crates.io publishes to crates.io from a job, such as a CI job, whose configuration does not.
699
+ :::
700
+
701
+ :::mara decision ADR-RELEASE-DEPENDENTS
702
+ :mid: 01M7DBRA91HC8EJYF8D7XME1FV
703
+ :title: Read the dependents of a release from the Cargo manifests, not from the project graph
704
+ :status: accepted
705
+ :justifies: DES-RELEASE
706
+
707
+ The maintainer's decision of 14 November 2026, with the option chosen, word for word: "Bump real dependents; rewrite everywhere (Recommended)". It settles how the release flow handles the plugin's `implicit` edges ([[DES-PROJECT-GRAPH]]).
708
+
709
+ The plugin returns every edge as `implicit`, so that Nx recomputes them on every graph computation ([[EVD-NX-EDGE-CACHE]]). Nx release takes the dependents of a project only from the `readDependencies` of its version actions, whose default leaves `implicit` edges out ([[EVD-NX-24-RELEASE]]). Version actions that kept the default would find no dependents. The two sources left are the project graph without the type filter and the manifests, through the `cargo metadata --no-deps` report of each workspace ([[DES-METADATA-REPORT]]):
710
+
711
+ | Case | Graph without the type filter | Manifests, through the report |
712
+ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- |
713
+ | Normal or build path dependency with a version requirement | Found | Found |
714
+ | Dev-dependency | Found, but the edge does not say that it is one | Found, with its kind |
715
+ | Path dependency without a version requirement | Found, requirement unknown | Found, with the requirement `*` |
716
+ | Optional, renamed or target-specific dependency | Found | Found, with the flags, the rename and the platform |
717
+ | Crate of another Cargo workspace | Found | Found, in that workspace's report |
718
+ | A crate that reaches the released crate through a crate without a project | An edge to the released crate, and with it a bump that the manifests do not ask for | No dependency; the crate in between names its own |
719
+ | Uses through `[patch]`, `[replace]` and `paths`, possible or assumed | An edge from every member with a registry or git dependency | None |
720
+ | The workspace project | An edge to every member | None |
721
+
722
+ The graph's edges are a superset built for cache keys and `nx affected` ([[DES-PROJECT-GRAPH]], [[ADR-REDIRECTION-EDGES]]). Read for release, they bump crates that never name the released crate and publish versions in which nothing changed. The version actions therefore read dependencies from the report. A crate becomes a dependent, and is bumped, through normal and build dependencies that carry a version requirement, which the crates that use it build. Dev-dependencies cause no bump by this choice, not by cargo's: the crates that use a crate never build its dev-dependencies, although cargo keeps a dev-dependency with a version requirement in the published manifest. Dependencies without a version requirement cause none either: cargo leaves such a dev-dependency out of the published crate and refuses to publish a crate with such a normal dependency ([[EVD-CARGO-PUBLISH]]). Every requirement on a bumped crate is rewritten in every manifest of the repository's Cargo workspaces, `[workspace.dependencies]` and crates outside the release included ([[DES-RELEASE]]), as cargo-release rewrites requirements over all members and the workspace root.
723
+
724
+ Rejected, beside the graph: bumping a crate for a dependency of every kind, as `@nx/js` does for npm packages, which releases crates in which nothing changes for the crates that use them; and updating only the requirements of the crates in the release, which is what Nx does by itself. After a breaking bump, a requirement left in a crate outside the release or in `[workspace.dependencies]` no longer matches the workspace's own crate, and every cargo command that resolves the workspace fails, the lockfile task's among them ([[EVD-CARGO-PUBLISH]]).
725
+
726
+ The costs: the report does not say where a requirement is written, in a member's table or in `[workspace.dependencies]`, so the version actions read and edit the manifests themselves; crates that are not released get changed manifests; and the rewriting is the plugin's own code, because Cargo has no command for it and cargo-edit's `cargo set-version` would be a tool for the user to install ([[ADR-V1-SCOPE]]).
727
+ :::
728
+
729
+ :::mara decision ADR-CACHED-FAILURES
730
+ :mid: 01M7DCSFF6ECEJBD0RE8ZDQRF9
731
+ :title: Leave to Nx and its NX_CACHE_FAILURES setting whether a failed task is stored
732
+ :status: accepted
733
+ :justifies: DES-OUTPUTS
734
+ :justifies: DES-LOCKFILE-HASHING
735
+ :justifies: DES-DIAGNOSTICS
736
+ :justifies: REQ-EXTERNAL-DEPS
737
+
738
+ The control plane's decision of 14 November 2026 under [[GOAL-TRUSTED-CACHE]], of which the maintainer is told. By default Nx stores nothing for a task that fails. With `NX_CACHE_FAILURES=true`, Nx stores the failure and replays it, as a failure, for the same key, also for a task that the plugin's executor fails before or after cargo runs ([[EVD-NX-24-BATCHES]]). The plugin leaves this to Nx, and every item that says what Nx stores for a failed task names the condition: by default nothing, with the setting the failure, and in neither case a successful result.
739
+
740
+ `NX_CACHE_FAILURES=true` is the user's own choice of an Nx setting. The plugin has no means to keep Nx from storing a result that its executor reports failed, and a stored failure is replayed as a failure, never as a success, so no result is trusted that should not be. What the setting costs falls on the user who chose it: a failure whose cause lies outside the key, such as a `Cargo.lock` that changed during the run, a missing tool or the network, is replayed until an input of the task changes or the cache is cleared with `nx reset`.
741
+
742
+ Rejected: keeping the items as they were, which promised that Nx stores nothing for a failed task whatever its settings.
743
+ :::
744
+
745
+ :::mara decision ADR-VERBOSE-COMMAND
746
+ :mid: 01M7DPAR45W1QX0DDQQ8535BFC
747
+ :title: Print a task's cargo command only when Nx runs verbosely, and let a verbose run's stored output keep it
748
+ :status: accepted
749
+ :justifies: REQ-VERBOSE-COMMAND
750
+ :justifies: DES-INVOCATION
751
+
752
+ The maintainer's decision of 14 November 2026, the option chosen, word for word: "Only with `--verbose` (Recommended)": normal output stays as it is, and with Nx's verbose flag each task prints the exact cargo command before running it. The options not taken: always printing it, and never printing it. The reason given with the question: since a command selects its crates by their package ID specifications ([[DES-INVOCATION]], "Selecting a crate"), it holds the checkout's absolute path, and Nx replays a task's stored terminal output, also on other machines through a shared cache, so the command stays out of normal output. Cargo's own hints for running a failed test again name the crate by its package name, which a workspace where another package of the resolve shares that name cannot use ([[EVD-CARGO-PACKAGE-SPECS]]), so without the command a user cannot run such a task by hand.
753
+
754
+ What a verbose run stores was left to the control plane, which settled it on 14 November 2026 under [[GOAL-TRUSTED-CACHE]], within the maintainer's answer: the stored output of a verbose run keeps the lines, and the user guide says so. Nx 24.0.6 stores everything that a task's process and its cargo write, and gives an executor no other way to the terminal ([[EVD-NX-24-VERBOSE]]). Keeping the lines out of the store would therefore mean leaving the run uncached, which a flag for output must not decide and which an executor cannot do for a task that succeeds. No restored result changes through the lines: a hit replays the terminal output as the run that stored the result printed it, as it replays cargo's own lines, which already name the crates' folders by their absolute paths. A user who wants to see the command of a task whose result is stored, without storing anything, runs it with `--skip-nx-cache --verbose`.
755
+
756
+ Rejected: writing the lines to the controlling terminal past Nx, which under Nx's pseudo-terminal is Nx's own and stores what arrives, does not exist in CI and would overwrite the terminal UI; printing the command without its folder, or with package names, which cannot be run where a name is ambiguous; and printing the lookups before the command as well ([[DES-INVOCATION]], "Printing the command").
757
+ :::
758
+
759
+ :::mara decision ADR-TEST-AFTER-BUILD
760
+ :mid: 01M7DJ8QGMASKGT057YS8Z9QBY
761
+ :title: Run a crate's test after its own build where cargo test replaces the executables of that build
762
+ :status: accepted
763
+ :justifies: DES-TARGETS
764
+ :justifies: DES-OUTPUTS
765
+ :justifies: DES-BATCH
766
+ :justifies: REQ-NO-RUST-TASK-DEPS
767
+ :accepts: RISK-ARTIFACT-DIR-WRITERS
768
+
769
+ For a crate with a binary and an integration test, `cargo test` replaces the executable that the crate's `build` declares as an output with one built with what dev-dependencies turn on and with the `test` profile, also when nothing needs compiling, and `CARGO_BIN_EXE_<name>`, which the tests run after cargo has released its build lock, names that same file. Nx copies a task's outputs into the cache some milliseconds after its process has ended, and a batch's when the whole batch has ended ([[EVD-CARGO-ARTIFACT-WRITERS]], [[EVD-NX-24-BATCHES]]). Where Nx ran a crate's `build` and `test` at the same time, as it did on `main` in milestone 0.1, it could store the executable of `cargo test` under the key of `build`, and the integration tests could run the executable of `build` and Nx store their result, against [[GOAL-TRUSTED-CACHE]]. A batch that ran a `build` group and then a `test` group stored the executable of `cargo test` every time.
770
+
771
+ On 14 November 2026 the maintainer chose, word for word, "`test` waits for own `build` (Recommended)". In the crates where `cargo test` replaces the executables of `build`, `test` depends on the same crate's `build`, so that the two never run at the same time and Nx stores `build` before `test` starts. The `test` executor fails a task whose run holds that `build` without the dependency, as where a configuration replaced it. In milestone 0.2, `build` and `doc`, the targets whose files Nx stores, run through a batch executor of their own, so that Nx stores their batch before it starts the batch of the tasks that depend on them ([[DES-TARGETS]], [[DES-BATCH]]). On 14 November 2026 the control plane settled its name, `@convesoft/nx-rust:cargo-outputs`.
772
+
773
+ Told to the maintainer with the choice, and accepted with it ([[RISK-ARTIFACT-DIR-WRITERS]]): after a command that runs both, the artifact directory holds what cargo wrote last, the executable of `cargo test`, as plain `cargo build && cargo test` leaves it, while the cache entries are right; two `nx` commands started at once can still overlap; and `run` with options that differ from those of `build` is not ordered.
774
+
775
+ The first of these consequences changed on 20 November 2026. A cached task outside the plugin that depends on `build`, runs its executable and starts after the `test` batch stored what it made of the test build ([[EVD-BATCH-FILES-ON-DISK]], nxr-5hzxra), and `cargo test` cannot build into a stage of its own as `build` does ([[ADR-STAGED-BUILDS]]). Asked "What should happen for tests?", the maintainer chose "Put builds' files back (Recommended)". As described to him, a `test` or `bench` batch keeps the executables of the command's cached builds and puts them back when it ends, so that after a batched command the artifact directory holds what `build` stored, not what `cargo test` wrote, which changes the consequence he accepted with this decision. A task that reads the file while the tests run can still get `cargo test`'s; that stays a stated limit, as does batching off. Not chosen: failing such test tasks, and stating the limit only. nxr-5hzxra implemented it ([[DES-BATCH]], "Files that a test batch puts back").
776
+
777
+ Rejected:
778
+
779
+ - **A plugin lock and a copy of the artifacts that the plugin owns.** Every cargo call of the plugin that can write executables would hold a lock per artifact directory for its whole run, and `build` would link its artifacts into a folder of the plugin while it holds the lock and declare that folder as its outputs. It closes both cases, also across `nx` commands that run at once, but builds wait for running test suites, the artifacts move out of the artifact directory, and a cache hit no longer puts a binary there, against [[ADR-RESULTS-ONLY-CACHE]] and [[DES-OUTPUTS]]. A lock alone leaves the wrong entries, because Nx copies the outputs after cargo has exited and released it.
780
+ - **A build directory of its own for tests.** A private artifact folder over the shared build directory fails beside plain cargo: `env!("CARGO_BIN_EXE_…")` is fixed when the test target is compiled, and the test target's fingerprint does not cover the folder, so after plain `cargo test` the tests ran a stale executable from the other folder, and the other way round. What remains, a whole build directory of their own for `test`, `bench` and `run`, compiles every crate and dependency twice, takes twice the disk and shares no work with plain `cargo test`, against [[REQ-CARGO-UNCHANGED]]; a variant that gives the crate's test profile an identity of its own through a profile setting per package changes how the crate is compiled and clashes with the repository's own profiles.
781
+ - **Not caching those builds.** The `build` of every crate with a binary and an integration test, which is most binary crates, would run uncached, a full compile in a cold CI each time, and the tests running the executable of `build` would still need a lock.
782
+
783
+ The costs: a command that runs `test` without `build`, such as `nx test api` or `nx affected -t test`, also runs or restores the crate's `build`, one more task, and on a cold build directory, where dev-dependencies or `[profile.test]` make the two executables differ, the plain build of what differs, which plain `cargo build` compiles as well. A dependency between two targets of one crate is not the dependency between crates that [[ADR-NO-RUST-BUILD-DEPS]] rejects: it orders two tasks that write the same files, and it compiles nothing twice.
784
+ :::
785
+
786
+ :::mara decision ADR-NAPI-SHARED-BUILD-DIR
787
+ :mid: 01M7J3B4MGB6VKYKPMJ2EVTA7K
788
+ :title: Compile Node addons in the shared build directory and accept the rebuilds this causes
789
+ :status: accepted
790
+ :justifies: DES-NAPI
791
+
792
+ The control plane took this decision on 16 November 2026, and the maintainer confirmed it on 20 November 2026.
793
+
794
+ To collect type definitions, the compile step of `napi-build` sets variables that the build scripts of napi crates watch ([[DES-NAPI]]). Cargo then rebuilds each crate whose build script calls `napi_build::setup()`, and every crate that depends on one of them, whenever those variables change. That happens on every `napi-build` compile and again on the next command without them: a plain `cargo build`, `nx build` or rust-analyzer's check ([[EVD-NAPI-POSTPROCESS]]). For those crates, `napi-build` and plain cargo invalidate each other's work, which [[NEED-CARGO-UNCHANGED]] says should not happen. There were two options:
795
+
796
+ - **The shared build directory**, chosen. Only the napi crates and what depends on them are compiled again; in the experiment, three napi crates and one ordinary library out of 41 units, in under 0.2 s against 6.9 s for the whole build. Addon crates are usually leaves, so what depends on them is usually nothing.
797
+ - **A build directory of its own for the napi compile.** It would leave plain cargo's work untouched, but compile everything a second time: under `workspace-build`, the whole workspace, and the extra build directory would grow as large as the first.
798
+
799
+ The shared directory costs less in the usual layout and is the easier of the two to change later: moving the napi compile to a directory of its own changes no output and no key. Where a napi helper sits deep in the dependency graph, its dependents pay the rebuild, and the maintainer may then prefer the other option.
800
+ :::
801
+
802
+ :::mara decision ADR-NAPI-RS-3
803
+ :mid: 01M7J3B4MG430J5R1KA7TD5WZW
804
+ :title: Build Node addons of napi-rs 3 only
805
+ :status: accepted
806
+ :justifies: DES-NAPI
807
+
808
+ The control plane took this decision on 16 November 2026, and the maintainer confirmed it on 20 November 2026.
809
+
810
+ `napi-build` serves crates built with `napi-derive` 3 and post-processed with `@napi-rs/cli` 3.4.0 or later, and fails with a message for any other version ([[DES-NAPI]]). The requirement behind the artifact targets names no version ([[REQ-ARTIFACT-TARGETS]]), so this leaves out existing napi-rs 2 addons. Two facts settle it ([[EVD-NAPI-POSTPROCESS]]). `@napi-rs/cli` 2 exports no functions, so only `napi build`, which runs cargo itself, could post-process with it. And it cannot build `napi-derive` 3 crates, whose macros refuse its variable. napi-rs 3 was announced in July 2025, and `@napi-rs/cli` 3.4.0, the first release that exports all three functions the plugin calls, dates from October 2025. Supporting napi-rs 2 would take a second path for post-processing, with type information in a single file; it can be added later without changing the path for napi-rs 3.
811
+ :::
812
+
813
+ ## Risks
814
+
815
+ Each risk below is backed by evidence, mitigated by a requirement or design, or
816
+ explicitly accepted by a decision (audited before 1.0 in nxr-fn1vas).
817
+
818
+ :::mara risk RISK-METADATA-KEY-COLLISION
819
+ :mid: 01M78FHG7F58QYEVQ7DX5KNQK5
820
+ :title: Another tool claims the nx metadata key
821
+ :status: accepted
822
+ :likelihood: unlikely
823
+ :consequence: moderate
824
+ :threatens: NEED-CONFIG-IN-CARGO
825
+
826
+ Another Nx plugin for Rust, or Nx itself, could start reading `[package.metadata.nx]` with a different meaning. Manifests would then carry settings two tools interpret differently, and one of them would have to move to another key. [[ADR-METADATA-KEY]] accepts this.
827
+ :::
828
+
829
+ :::mara risk RISK-TARGET-DEFAULTS
830
+ :mid: 01M78FHG7FAJAK7K2EN2P4XE8C
831
+ :title: Target defaults written for JS reach Rust targets
832
+ :status: accepted
833
+ :likelihood: likely
834
+ :consequence: major
835
+ :threatens: NEED-EFFICIENT-BUILDS
836
+ :threatens: NEED-CORRECT-CACHE
837
+
838
+ Because Rust targets share the names `build`, `lint` and `test` with JS targets, a `targetDefaults` entry keyed by a bare name applies to them. Nx 24 lays the entry over the inferred target: its `dependsOn`, `inputs`, `outputs` and `cache` replace the inferred values unless a list keeps them with `"..."`, and its `options` reach the executor ([[EVD-NX-TARGET-DEFAULTS]]). A `dependsOn: ["^build"]` then adds a build of every crate a crate depends on ([[EVD-NXRUST-BUILD-DEPS]]); batching ([[DES-BATCH]]) puts them in one batch with the build that needs them. An `inputs` list written for a JS tool drops the toolchain, environment and workspace inputs from the key, so a result built under other settings is restored. An `outputs` list drops the artifacts, so a cache hit restores no binary, and `cache: true` caches the targets that the plugin leaves uncached because their artifacts lie outside the repository. A `filter` on projects, plugin or executor keeps an entry away from Rust targets ([[EVD-NX-24-INSPECTION]]), but a `plugin` filter cannot select targets from `package.json` scripts or `project.json` files. The executor runs a task without the options it does not know and says so in the task's output, which mitigates what an entry's options do ([[REQ-UNKNOWN-OPTIONS]]). [[REQ-TARGET-DEFAULT-GUARD]] mitigates the rest: the plugin reports such an entry, as an error where Nx could restore a result that the task would not produce.
839
+ :::
840
+
841
+ :::mara risk RISK-GUARD-HASH-PLAN
842
+ :mid: 01M7FQT51YQ82Y4SVCT9JATHDP
843
+ :title: The target-default guard reads a list otherwise than Nx's native hash plan
844
+ :status: accepted
845
+ :likelihood: unlikely
846
+ :consequence: major
847
+ :threatens: GOAL-TRUSTED-CACHE
848
+ :threatens: NEED-CORRECT-CACHE
849
+
850
+ [[DES-TARGET-DEFAULT-GUARD]] judges what another plugin does to an inferred target's `inputs` by expanding them as the JS helpers of Nx's task hasher do. Nx hashes a task by the plan of its native `HashPlanner`, which receives the lists unexpanded ([[EVD-NX-24-PLUGIN-NODES]], "What a list means"). The two readings differ in both directions. The re-check of 15 November 2026 showed these cases:
851
+
852
+ 1. A self input written as `{ "input": <name>, "dependencies": false }`, whose definition the guard does not expand, lets a later plugin's named input with a negated pattern take a crate's sources out of its key.
853
+ 2. A later plugin that defines `default` anew for a crate that another crate reads through `^default`, where the first crate's own targets read another named input, takes that crate's sources out of the other's key, because the guard does not compare the definitions that a `^` input reads.
854
+ 3. A later plugin's negated pattern that the native plan does not apply, such as `"!{workspaceRoot}/rust/crates/api/src/**/*"` or `{ "fileset": "!{projectRoot}/src/**/*", "dependencies": true }`, is refused although the key stays the same.
855
+
856
+ Cases 1 and 2 end in a stale cache hit, but only where a second plugin contributes these particular forms to a crate's own project. Case 3 is a false refusal, which the fixes that the message offers get past: an `exclude` on that plugin's entry, or the change written into the crate's `project.json`. For a target without `inputs`, the native plan also held a crate's files where a later plugin defined `default` anew, unlike the JS helpers' expansion that the guard copies. The planned mitigation (`nxr-2vzmt5`: compare what the native planner plans for the merged target and for the guard's rebuild, or close cases 1 to 3 one by one) was deferred to the backlog on 15 November 2026 by the maintainer's rule for exotic findings, since all three cases require a second Nx plugin rewriting a crate's own targets.
857
+ :::
858
+
859
+ :::mara risk RISK-UNDECLARED-INPUTS
860
+ :mid: 01M78FHG7F7QAFW6P09CQYEPJA
861
+ :title: A task reads something its cache key does not cover
862
+ :status: accepted
863
+ :likelihood: possible
864
+ :consequence: major
865
+ :threatens: GOAL-TRUSTED-CACHE
866
+ :threatens: NEED-CORRECT-CACHE
867
+
868
+ A build script, proc macro or test can read files outside the crate, environment variables outside the allowlist, or the network. A change there does not change the key, and a stale result is restored. The plugin declares what it knows: it hashes the whole folder of a crate and of a path dependency without a project, and warns where Nx cannot see such a dependency's files. A repository adds the files outside a crate that the crate reads ([[REQ-BUILD-SCRIPT-INPUTS]]), and variables and commands. A `build` that ran cargo fails when Cargo's dependency files name a repository file that no input covers ([[REQ-BUILD-INPUT-CHECK]]).
869
+
870
+ What remains: a file that a proc macro opens without an include macro, which Cargo does not track and no dependency file shows; files that only `check`, `lint`, `test` or `doc` read, or that tests open at run time, since Cargo records those reads only in its build directory or not at all; any undeclared read of a crate whose `build` does not run through Nx, as in a pipeline that runs only `lint` and `test`; files outside the repository, which Nx cannot hash; environment variables outside the list; and the network ([[EVD-CARGO-DEP-INFO]]). Without a sandbox the plugin cannot detect these. [[ADR-V1-SCOPE]] accepts this.
871
+ :::
872
+
873
+ :::mara risk RISK-HOST-ENVIRONMENT
874
+ :mid: 01M78FHG7F36BVH0EP3K2REH3E
875
+ :title: A result is restored on a machine that differs in ways the key cannot see
876
+ :status: accepted
877
+ :likelihood: possible
878
+ :consequence: moderate
879
+ :threatens: NEED-CORRECT-CACHE
880
+
881
+ The key contains the toolchain, including the host triple, and the target triple. It does not contain system libraries, the linker, the C toolchain version, Cargo and tool configuration outside the repository, such as `$CARGO_HOME/config.toml` or a rustfmt configuration in the home directory, or a configuration file inside the repository that an ignore rule leaves out of the files that Nx reads, apart from the triples, the compiler and the rustdoc that such a configuration picks and the Clippy configuration files that `CLIPPY_CONF_DIR` can select, also through such a configuration's `[env]` ([[DES-INPUTS]]). A compiler or rustdoc named there is read when Nx creates the graph, so under the Nx daemon a change to it counts only once the graph is created again. With a cache shared between unlike machines of one triple, a test result or a dynamically linked binary from one can be restored on another where it would behave differently. A repository can add a runtime input that tells its machines apart. [[ADR-V1-SCOPE]] accepts this. The key does not contain the checkout's folder either ([[DES-INVOCATION]]), so a `build` restored in another checkout on the same machine, which Nx 24's per-user cache allows by default, brings executables whose compiled-in paths, such as `env!("CARGO_MANIFEST_DIR")`, name the checkout that built them. On 22 November 2026 the maintainer accepted this as part of this risk; a repository that needs its own paths gives `build` an input that names the checkout ([Caching](caching.mara.md#sharing-the-cache-between-checkouts)).
882
+
883
+ On 14 November 2026 the maintainer kept this risk for Cargo configuration that Nx does not hash, with the option he chose, word for word: "Keep the risk, warn clearly". No key changes. The plugin warns for every Cargo configuration file that it reads and that Nx does not hash, where the file sets something that can change a build or a check, and says that after a change to it the cache has to be reset with `nx reset` or the tasks run with `--skip-nx-cache` ([[DES-DIAGNOSTICS]]). The two reproductions in [[EVD-CARGO-REDIRECTIONS]] show what the warning names: with the Nx daemon, a `[patch]` switched to another crate of the same name, version and dependencies, and without the daemon a changed `[env]` value in an ignored `.cargo/config.toml`, gave a cache hit for a build that cargo would have done differently. The options not taken were hashing the text of those files into every key, and hashing only their build-affecting tables with a script at hash time; both would give the tasks of every developer with a global Cargo configuration keys of their own.
884
+
885
+ On 22 November 2026, after `1.0.0-rc.1` restored a cached `lint` past a change to the `clippy.toml` in the folder that `CLIPPY_CONF_DIR` names, the maintainer answered, word for word: "keep external Cargo config (`$CARGO_HOME/config.toml`, etc.) and per-user Rustfmt config (`$XDG_CONFIG_HOME/rustfmt/rustfmt.toml`, `~/.config/rustfmt/rustfmt.toml`, `~/.rustfmt.toml`) accepted under `RISK-HOST-ENVIRONMENT` rather than hashing them into cache keys, and emit the same clear graph-creation warning for per-user Rustfmt configuration outside the repository that the plugin already emits for external Cargo configuration." So a per-user rustfmt configuration file that rustfmt takes for a crate draws a warning in the `fmt-check` and `fmt` tasks of that crate and in no key ([[DES-DIAGNOSTICS]]). A rustfmt configuration file in a folder above the repository, which rustfmt takes before the per-user ones and for the same reason ([[EVD-CLIPPY-RUSTFMT-CONFIG-LOOKUP]]), draws the same warning: that follows from the rule of 14 November 2026 for configuration outside the repository, "Keep the risk, warn clearly", and is not part of the answer of 22 November. The Clippy configuration that `CLIPPY_CONF_DIR` selects is not of this kind: the variable comes from the task's environment, which the key already follows, or from Cargo's `[env]`, which graph creation reads, and `lint` has a runtime input that prints the files of every such folder ([[DES-INPUTS]], "Clippy's configuration folder"). A `clippy.toml` above the repository that clippy takes where the variable is unset and no folder of the repository holds one stays within this risk, still without a warning. On 22 November 2026 the maintainer chose for it, word for word: "Warn, after rc.2: same rule as for Cargo and rustfmt ("keep the risk, warn clearly"), but it stays in the backlog until rc.2 is out." (nxr-8akbay).
886
+ :::
887
+
888
+ :::mara risk RISK-SUBSET-AS-FULL
889
+ :mid: 01M78FHG7FECGDXGMB8MB75DPD
890
+ :title: A subset test result is reused as a full-suite result
891
+ :status: accepted
892
+ :likelihood: unlikely
893
+ :consequence: severe
894
+ :threatens: REQ-TEST-MODE-KEY
895
+ :threatens: GOAL-TRUSTED-CACHE
896
+
897
+ If the result of running selected tests were stored under the key of the full suite, the main branch could show green for tests that never ran. [[DES-TEST-MODE]] prevents it by putting the mode and the baseline commit into the key, and by letting a task select only where every evaluation of the mode command in its `nx` command printed the mode that its executor reads, with a value that is never restored for an evaluation after a subset ran in another mode ([[EVD-TEST-MODE-GUARD]]). The remaining exposure is the mode command reporting another mode than the one the task runs in, for example when Nx reuses an old evaluation or runs the command in another environment than the task ([[RISK-NX-INPUT-SEMANTICS]]). A run of the test target that the `test` option names is a subset as well: the option is in its key, the task runs in a cargo command of its own, and it never selects affected tests, so its result is neither stored under the key of the whole suite nor counted for another crate ([[DES-TEST-RUN]], "One test target"; [[DES-BATCH]], "Groups of one crate").
898
+ :::
899
+
900
+ :::mara risk RISK-NX-INPUT-SEMANTICS
901
+ :mid: 01M78FHG7FWVEHYKF3KRPQYTWN
902
+ :title: Nx evaluates inputs differently from what the design assumes
903
+ :status: accepted
904
+ :likelihood: unlikely
905
+ :consequence: major
906
+ :threatens: REQ-TEST-MODE-KEY
907
+ :threatens: REQ-TOOLCHAIN-KEY
908
+ :threatens: NEED-AFFECTED
909
+ :threatens: REQ-ENV-ALLOWLIST
910
+
911
+ The design assumed that a runtime input is evaluated afresh on each run, also under the Nx daemon; that its command runs through a shell from the repository root, so that it can change into a workspace folder, and with the environment of the `nx` command; that task-based affected treats runtime inputs and batched tasks the way the cache does; and that `^` inputs hash stably when projects form a cycle. Nx 24.0.6 confirms most of this ([[EVD-NX-24-INPUT-SEMANTICS]]). It evaluates a runtime input once per task of every run, also under the daemon, through `sh -c` in the repository root, with the environment of the `nx` command plus the dotenv files it loads for the task. Batched and unbatched runs select the same tasks and share their keys, and `^` inputs hash stably over a project cycle. Two differences remain.
912
+
913
+ In a batch, Nx computes each task's key with an environment it rebuilds for that task from dotenv files, but starts the batch process with the environment of the `nx` command, into which it loaded only the root `.env`, `.env.local` and `.local.env`, and in another order of priority. The two differ when a file in the crate's folder or a root file named for a target or configuration, such as `.env.test`, sets a variable; when `.env.local` and `.local.env` set it differently; and when a shell value equal to a root file's value is unloaded for the task ([[EVD-NX-24-INPUT-SEMANTICS]]). A test mode, a toolchain or a listed variable is then in the key of a task that runs with another value. A result could be stored under a key that does not describe it, a subset result under the full-suite key among them ([[RISK-SUBSET-AS-FULL]]). This takes batching and dotenv files that set one of these variables. [[DES-BATCH]] rebuilds each task's environment from the same files and runs every cargo call with it. That copy of Nx's loading is the remaining exposure: a later Nx that reads other files, or in another order, would bring the gap back.
914
+
915
+ Task-based affected selects tasks by changed files, never by environment variables or the output of runtime commands. A toolchain update without a change to a toolchain file, or a new value of a listed variable, makes no task affected, although it changes the keys. A task that does run still misses the cache, so no stale result is restored, but `nx affected` does not run the tasks such a change reaches.
916
+ :::
917
+
918
+ :::mara risk RISK-BATCH-BEHAVIOUR
919
+ :mid: 01M78FHG7FARJNEMM2EFX7XFY9
920
+ :title: Nx batches behave worse than the design needs
921
+ :status: accepted
922
+ :likelihood: likely
923
+ :consequence: major
924
+ :threatens: REQ-BATCHING
925
+ :threatens: NEED-EFFICIENT-BUILDS
926
+
927
+ On Nx 24.0.6, an executor with `preferBatch` is batched without `--batch`, and Nx hashes each task of a batch with that task's environment, restores a task on its own and then leaves it out of the batch, and stores and replays each task's own result and terminal output ([[EVD-NX-24-BATCHES]], [[EVD-NX-24-INPUT-SEMANTICS]]). Per-task results and per-task caching hold. Three things are worse than the design needs:
928
+
929
+ - While a batch runs, Nx starts no other task, whatever `--parallel` allows. Tasks that started before the batch run on, and a task that depends on any task of the batch waits for the whole batch, so in a mixed repository JS tasks wait for the Rust batch. [[ADR-BATCH-EXECUTOR]] accepts this.
930
+ - Nx stores the results and declared outputs of a batch's tasks only when the whole batch has ended. A later group of the batch that writes the declared outputs of an earlier task changes what Nx stores under that task's key, as `cargo test` does with the executable of a crate's `build` when a dev-dependency enables other features. This refutes an assumption of [[DES-BATCH]], that the groups of a batch can run one after another while Nx stores each task's result as it would for the task run alone. [[DES-BATCH]] therefore runs `build` and `doc`, the targets whose files Nx stores, through a batch executor of their own, so that Nx stores their batch before it starts the batch of the tasks that depend on them, such as the `test` that waits for a crate's `build` ([[ADR-TEST-AFTER-BUILD]], [[EVD-CARGO-ARTIFACT-WRITERS]]).
931
+ - Nx takes results in one shape only. A throw or an exit of the batch fails each of its tasks and stores nothing, unless `NX_CACHE_FAILURES=true`, under which Nx stores a failure for each of them that later runs replay without starting a batch. A task left out runs again in a new batch process. Storing a result without terminal output fails and ends the run, while with `--skip-nx-cache` the same results pass. Without `NX_CACHE_FAILURES=true`, Nx stores a task only with the status `success`; with it, a reported failure is stored and replayed as well. Any other status than `success`, `failure` and `skipped` stops Nx with an error, storing nothing, when a generator streams it, and leaves the task unstored in a successful run when it comes in one object of results. A line that the batch process prints itself belongs to no task.
932
+
933
+ On 14 November 2026 the control plane of the work decided that the text, likelihood and consequence of this risk follow these experiments, without asking the maintainer again.
934
+ :::
935
+
936
+ :::mara risk RISK-HAKARI-GAPS
937
+ :mid: 01M78FHG7F2NTRC9DZ1NMXWY7V
938
+ :title: cargo-hakari does not unify everything the plugin relies on
939
+ :status: accepted
940
+ :likelihood: unlikely
941
+ :consequence: major
942
+ :threatens: REQ-STABLE-FEATURES
943
+
944
+ cargo-hakari unifies the features of third-party crates only. It leaves to the selection the features of members, of third-party crates that depend on a member through normal or build dependencies, and of dependencies under platform tables on platforms that its configuration does not list, and its excludes and the `version-only` line style leave further crates out; `cargo hakari verify` and `generate --diff` report none of these ([[EVD-HAKARI-UNIFICATION]]). Cargo itself applies feature flags to the crates that a command selects. [[DES-UNIFICATION]] therefore uses the hack crate only where four checks at graph creation show that none of the gaps of cargo-hakari applies, and otherwise builds the whole workspace, which costs time where it applies; it applied in both workspaces with cargo-hakari that were examined, guppy and nextest, because their members ask features of each other. A group whose flags act on the selected crates, or that builds for a triple that `platforms` does not list, runs one crate per command ([[DES-BATCH]]), and the uncached drift check keeps a stale hack crate from storing results.
945
+
946
+ What remains is a gap that none of these sees, so that a crate's result depends on its batch under a key that does not change:
947
+
948
+ - **Changes that graph creation does not see in time.** A redirection to a member, or another change to a configuration file outside the repository or one that Nx ignores, made while the Nx daemon keeps a graph that chose `hakari`, counts only when Nx creates the graph again, as for the edges ([[RISK-HOST-ENVIRONMENT]]).
949
+ - **Shapes that the experiments did not cover.** The settings that the fourth check accepts were tried on one workspace with normal, build and dev-dependencies, a platform table and a crate used on the host and the target, not with proc macros, renamed or optional third-party dependencies, or several versions of one crate.
950
+ - **What cargo-hakari's own checks miss.** The drift check relies on `generate --diff` and `manage-deps --dry-run`, which caught every stale case tried, not every possible one.
951
+
952
+ The likelihood is unlikely: the first needs a change outside the repository while the daemon runs, which the warning about such a file names; the second a shape where cargo-hakari unifies otherwise than in what was tried; the third a stale hack crate that both commands accept. The consequence stays major: Nx restores a result built with other features, which can hide a failing build or test.
953
+ :::
954
+
955
+ :::mara risk RISK-CARGO-AFFECTED
956
+ :mid: 01M78FHG7F5EH60R4TW2E645EW
957
+ :title: cargo-affected does not deliver what the test design assumes
958
+ :status: accepted
959
+ :likelihood: possible
960
+ :consequence: major
961
+ :threatens: REQ-AFFECTED-TESTS
962
+ :threatens: NEED-FAST-TESTS
963
+
964
+ cargo-affected describes itself as extremely early. The design assumed that `status --report-json --report-detail full` lists tests precisely enough to build a nextest filter and to map results to crates, and that `status` is cheap although it lists tests through nextest, which needs built test binaries. Both held on ripgrep, tokio and a fixture: nextest ran exactly the selected tests, every result mapped to its crate, and status builds only what the run then uses ([[EVD-CARGO-AFFECTED-REPORT]], [[EVD-CARGO-AFFECTED-COST]]). A correct filter can still leave out failing tests, so they hold only with the conditions that [[DES-TEST-RUN]] now sets: git's `diff.relative` for a workspace below the top of its repository, the plugin's own check of the changed files against git, the selection on the command line, a baseline used only in the context it was collected in ([[ADR-AFFECTED-BASELINE-CONTEXT]]), and coverage narrowing only changes whose whole effect it records, with every other change widened by the tasks' inputs ([[ADR-AFFECTED-TESTS-WIDENING]]).
965
+
966
+ What remains is code that another crate evaluates while it compiles, such as a `const fn` used in a `const` or a macro by example, which leaves no coverage for that crate's tests and is a stated limit; a test that starts a program or reads a file without a declared relation, whose key is wrong without affected mode too; and a later cargo-affected that reports otherwise, which runs the full suite where the plugin does not recognise the report. The likelihood is possible. The consequence is major: a pull request's affected run can pass where the full suite fails. The selector stays a replaceable step and the feature is off by default.
967
+ :::
968
+
969
+ :::mara risk RISK-COVERAGE-COST
970
+ :mid: 01M78FHG7F5ES0QNZ84J94JZQ2
971
+ :title: Collecting coverage costs too much on main
972
+ :status: accepted
973
+ :likelihood: likely
974
+ :consequence: moderate
975
+ :threatens: NEED-FAST-TESTS
976
+
977
+ The baseline runs `cargo affected collect --diff` on every main commit, and a full `collect` where no usable baseline exists. What that costs depends on the workspace ([[EVD-COVERAGE-COLLECT-COST]]). On ripgrep it costs about as much as the plain test run of the same commit. On rust-analyzer, whose 8,314 tests run in 21 s at 4 threads, a full `collect` took eleven minutes, `--diff` 52 s for a commit that changed no Rust, 1.5 minutes for a change to a leaf crate and 12.5 to 14 minutes for a change to a core crate, and the database that the pipeline saves for every commit held 8.75 GB, 404 MB compressed. Collection runs every test it re-collects under instrumentation, and its cost grows with the number of tests and the code they reach, so a workspace with many fast tests, like rust-analyzer, pays far more on main than selection can save on pull requests ([[EVD-CARGO-AFFECTED-COST]]). Slow tests do not make the trade sure either: where they are integration tests that start a binary or read shared files, the widening of [[DES-TEST-RUN]] can select the whole suite for common changes and leave only the overhead. What pull requests save after that widening, the upkeep of the baseline over many commits and moving the database between CI runs were not measured. The likelihood is likely for workspaces with many fast tests and unknown for the rest. The consequence stays moderate: the main pipeline slows down and the CI cache fills, but no result is wrong.
978
+
979
+ What limits it: `affectedTests` is off by default, so only a workspace that turns it on pays, and it can turn it off again. [[DES-BASELINE]] starts a full `collect` without the previous database, which on rust-analyzer took 652 s where writing over the old one took 957 s. The user guide gives the measured costs, says that slow tests make a workspace a candidate and no more, and gives the commands to measure representative changes in one's own repository before switching the feature on ([Continuous integration](ci.mara.md#the-coverage-baseline)). Instrumented and normal builds did not evict each other in Cargo's directories, so they need no separate build directory for that. Collection runs with the parallelism that the pipeline sets, and its memory grows with it: at 4 jobs and 4 test threads rust-analyzer's collection stayed under 7 GiB, page cache included, while at cargo's and nextest's defaults on a 16-core machine with 14 GB a collection ran while the kernel's out-of-memory killer ended other processes.
980
+ :::
981
+
982
+ :::mara risk RISK-BASELINE-DRIFT
983
+ :mid: 01M78FHG7F90XWFCQ150XBFKGM
984
+ :title: Selection gets noisy as the baseline falls behind
985
+ :status: accepted
986
+ :likelihood: possible
987
+ :consequence: minor
988
+ :threatens: NEED-FAST-TESTS
989
+
990
+ A pull request compared against an older baseline has a wider diff and selects more tests. How quickly that happens is inferred from how cargo-affected stores its data and will be observed during real-repository validation rather than blocking 1.0, because the consequence is only lost time (never a wrong result) and `affectedTests` is off by default. The full recollect threshold in [[DES-BASELINE]], `fullCollectThreshold` (default 100 commits), is the user-tunable control.
991
+ :::
992
+
993
+ :::mara risk RISK-UPSTREAM-CHANGES
994
+ :mid: 01M78FHG7F662HG5KVZQEN15Z3
995
+ :title: Unstable upstream interfaces change under the plugin
996
+ :status: accepted
997
+ :likelihood: likely
998
+ :consequence: moderate
999
+ :threatens: NEED-EFFICIENT-BUILDS
1000
+ :threatens: NEED-FAST-TESTS
1001
+
1002
+ Several things the plugin uses are not stable: Cargo's `resolver.feature-unification`, whose name or values could still change; the layout of the build directory, which changed in Cargo 1.100; cargo-affected's commands and report format; Nx's batch executor interface; how Nx copies the plugin for each entry of `nx.json` and calls its hooks, which links an entry's hooks to each other and which Nx does not document ([[EVD-NX-24-PLUGIN-ENTRIES]]); and the private `nx/src/*` modules that `init`, graph creation and executors load (`nx/src/devkit-internals`, `nx/src/project-graph/plugins/get-plugins`, `nx/src/project-graph/utils/retrieve-workspace-files`, `nx/src/project-graph/utils/project-configuration/project-nodes-manager`, `nx/src/plugins/package-json`, `nx/src/plugins/project-json/build-nodes/project-json`, `nx/src/utils/workspace-context`, `nx/src/native`, `nx/src/hasher/hash-plan-inspector`, `nx/src/hasher/task-hasher`, `nx/src/tasks-runner/task-env` and `nx/src/tasks-runner/create-task-graph`), which Nx does not count as public API. The plugin routes every private `nx/src/*` load and `nx/package.json` lookup through one internal bridge, which looks for the repository's Nx in `.nx/installation` and then at the repository root, and uses the plugin's own peer dependency only where the repository has no `nx` package at all. It never mixes the two: a private module that is missing from the repository's Nx is an error, not a reason to load the peer's, and a resolution error other than a missing module is reported as it is. The bridge checks the shape of each export that a caller uses before the caller calls it. For dotenv checking ([[DES-BATCH]], "Dotenv files"), the plugin no longer pins an exact version of `dotenv-expand` at run time or re-implements its expansion loop; instead, its static reference check follows the recorded matching (`/(?<!\\)\${([^{}]+)}|(?<!\\)\$([A-Za-z_][A-Za-z0-9_]*)/g`), splitting (including `split(null)` on literal `"null"`), `(?<!\\)` escaping, and `String.prototype.replace` behaviour of Nx's `dotenv-expand`, guarded by a source-text tripwire test on `dotenv-expand`'s `lib/main.js` ([[EVD-DOTENV-STATIC-CHECK]], [[VER-BATCHING]]). The plugin also avoids the build directory layout entirely, keeps the `cargo` strategy experimental and the selector replaceable, fails graph creation where it cannot tell which entry a hook belongs to ([[DES-DISCOVERY]]), and supports only the Nx majors it has been verified on ([[ADR-COMPATIBILITY]], which accepts this ongoing maintenance risk while tracking Cargo's stabilisation and later Nx majors).
1003
+ :::
1004
+
1005
+ :::mara risk RISK-MIXED-PROJECT-MERGE
1006
+ :mid: 01M78FHG7FMS3SAP65G9TME7FF
1007
+ :title: Two plugins describe one folder differently
1008
+ :status: accepted
1009
+ :likelihood: almost-certain
1010
+ :consequence: moderate
1011
+ :threatens: NEED-JS-BRIDGE
1012
+ :threatens: REQ-WORKSPACE-PROJECT
1013
+ :threatens: REQ-PROJECT-NAMES
1014
+
1015
+ A napi or wasm crate usually has `Cargo.toml` and `package.json` side by side, so this plugin and Nx's `package.json` plugin both create a project for the folder. Nx merges them into one project, and it applies `package.json` and `project.json` after every plugin listed in `nx.json` ([[EVD-NX-PROJECT-MERGE]]). The project is therefore named by `package.json`, or by a `project.json` that sets a name, and not after the crate. A script or `project.json` target that has the name of an inferred target, such as `build` or `test`, and runs something else replaces the inferred target, with its cache settings and inputs, without a message. The same happens to the workspace project when a Cargo workspace sits in a folder that already is an Nx project, such as a repository root with a `project.json` or with an `nx` key in its `package.json`. An edge that names such a project by its crate name is dropped without a message or fails graph creation, while a `dependsOn` entry that names it is rewritten to the new name. [[REQ-MIXED-PROJECTS]] mitigates it by making the outcome predictable rather than different: the plugin keeps its names, leaves replaced targets to the files that replace them, and documents the means Nx offers to keep a target, while a replaced lockfile task makes the crates' tasks fail rather than store a result ([[ADR-MIXED-PROJECT-TARGETS]]). Verified on Nx 24.0.6 ([[EVD-NX-PROJECT-MERGE]]); later Nx majors are verified before joining the peer range under [[ADR-COMPATIBILITY]].
1016
+ :::
1017
+
1018
+ :::mara risk RISK-NAPI-TOOLING
1019
+ :mid: 01M78FHG7F2Q33HWV789RWB7T7
1020
+ :title: The napi CLI does not fit the two-step build
1021
+ :status: accepted
1022
+ :likelihood: possible
1023
+ :consequence: minor
1024
+ :threatens: REQ-ARTIFACT-TARGETS
1025
+
1026
+ [[DES-NAPI]] keeps compiling in the batch and post-processes the build with functions that `@napi-rs/cli` exports, because `napi build` always runs cargo itself ([[EVD-NAPI-POSTPROCESS]]). The first assumption of this risk, that the napi CLI can post-process an existing cargo build, was checked on Linux with `@napi-rs/cli` 3.10.12 and holds in that form. Plain `cargo test` also compiles, links and runs Rust unit tests (including tests calling `#[napi]` functions) on Linux with `napi` 3.16.2 and `napi-sys` 3.4.1 without any special feature, because `napi-sys` enables `dyn-symbols` by default via `libloading` ([[EVD-NAPI-POSTPROCESS]]). What remains rests on contracts of napi-rs that its documentation does not promise: the exported functions `generateTypeDef` and `writeJsBinding` and their options, the variables `NAPI_TYPE_DEF_TMP_FOLDER` and `NAPI_FORCE_BUILD_<CRATE>`, and the `rerun-if-env-changed` lines of `napi_build::setup()`. A minor release can change them. The CLI's version is part of the key, so a change makes `napi-build` fail or write other files, and does not restore a wrong result; `napi-derive` is part of the lockfile.
1027
+ :::
1028
+
1029
+ :::mara risk RISK-MACOS-UNVERIFIED
1030
+ :mid: 01M78KFPPYBZHRM9B41K0TG46Q
1031
+ :title: macOS support breaks without anyone noticing
1032
+ :status: accepted
1033
+ :likelihood: possible
1034
+ :consequence: moderate
1035
+ :threatens: REQ-COMPATIBILITY
1036
+
1037
+ While CI runs on Linux only, nothing runs the plugin on macOS. A change that works on Linux can fail there, for example through a case-insensitive file system, a different linker and library naming for Node addons, or different toolchain paths, and the failure reaches users first. Until macOS runs exist, the claim that macOS is supported rests on the design and not on test runs. [[ADR-CI-LINUX-ONLY]] accepts this for the moment.
1038
+ :::
1039
+
1040
+ :::mara risk RISK-TEST-RUNNER-MACOS
1041
+ :mid: 01M7DMTE8WRK2WHQ2R4VXJTWQ3
1042
+ :title: The selecting test runner fails test binaries on macOS that pass under plain cargo
1043
+ :status: accepted
1044
+ :likelihood: possible
1045
+ :consequence: moderate
1046
+ :threatens: REQ-COMPATIBILITY
1047
+ :threatens: REQ-BATCHING
1048
+
1049
+ The selecting runner of [[DES-TEST-RUN]] has run on Linux only, and CI runs on Linux only ([[ADR-CI-LINUX-ONLY]]). It runs test binaries only; doctests run without it. It is a Node script, also because macOS removes `DYLD_*` variables from the environment of a binary that System Integrity Protection protects, such as `/bin/sh` and `/usr/bin/env`, while cargo passes a test's library path in `DYLD_FALLBACK_LIBRARY_PATH` there ([[EVD-WORKSPACE-TEST-SELECTION]]). Not verified on macOS:
1050
+
1051
+ - that macOS keeps those variables for the Node that runs Nx, which a build with the hardened runtime and without the entitlement that allows them may drop; the builds that users install, from the official installer and archives, Homebrew and version managers, were not checked;
1052
+ - that cargo's JSON messages name every test executable there as on Linux, and that exit statuses and signals pass through Node's child process as on Linux.
1053
+
1054
+ What the evidence of [[DES-TEST-RUN]] guarantees does not rest on the host's terminal output: a test task passes the test binaries' step only where every test executable that cargo's messages name for its crate has a record that ends with the status 0 ([[EVD-TEST-STEPS-SPLIT]]). A lost library path therefore shows as failed test binaries, whatever status dyld gives, and never as a pass, as does a Node runner that does not start, that fails, or that a preload in `NODE_OPTIONS` ends before it records anything. A test binary that cannot load its libraries also fails by its own exit status under plain semantics, which cargo reports.
1055
+
1056
+ The consequence is moderate: tests that need cargo's library path, such as one linked against a `dylib` member, fail under `workspace-build` on such a machine, with a message that shows the loader's error but not its cause, and nothing wrong is stored ([[GOAL-TRUSTED-CACHE]]). The likelihood is possible: few tests load dynamic libraries from the build folder, and whether common Node builds drop the variables is unknown. The remedy would be a runner program that keeps the variables. The maintainer accepted the risk when he chose the selecting runner ([[ADR-TEST-SELECTING-RUNNER]]).
1057
+ :::
1058
+
1059
+ :::mara risk RISK-TERMINAL-ENVIRONMENT-MACOS
1060
+ :mid: 01M7F8NEP74P35FFBKMAVR6SXB
1061
+ :title: A task's environment in a terminal on macOS differs from the one that was verified
1062
+ :status: accepted
1063
+ :likelihood: unlikely
1064
+ :consequence: moderate
1065
+ :threatens: REQ-BATCHING
1066
+ :threatens: REQ-COMPATIBILITY
1067
+
1068
+ [[VER-BATCHING]] runs the ways of running a task in a terminal, where Nx starts a single task in its native pseudo-terminal, on Linux only: the test gives Nx a terminal through util-linux's `script -qfec`, whose arguments macOS's own `script` does not take, and stops it with coreutils' `timeout`, which macOS lacks. CI runs on Linux only ([[ADR-CI-LINUX-ONLY]]). On macOS the ways without a terminal run as on Linux, and what Nx sets in JavaScript for a task in its pseudo-terminal is the same code ([[EVD-NX-24-BATCHES]], "Task environment"). Not verified is whether the macOS build of Nx's native pseudo-terminal gives the task's process variables that the Linux build does not, such as `TERM`, `COLUMNS` or `LINES`, which no run on Linux showed. Such a variable would reach cargo for a task run on its own in a terminal and not in a batch or in another output style, so that two results could be stored under one key ([[GOAL-TRUSTED-CACHE]]), for a build script or test that reads it. The likelihood is unlikely, since the Linux build adds none; the remedy is to run the test with macOS's `script -q /dev/null` and a timeout of the harness's own once macOS runners are usable, and to leave out what it finds.
1069
+ :::
1070
+
1071
+ :::mara risk RISK-ARTIFACT-DIR-WRITERS
1072
+ :mid: 01M7DJ8QGM2WH33TJ7HBG7XRD0
1073
+ :title: Cargo calls that Nx does not order write the files that build stores
1074
+ :status: accepted
1075
+ :likelihood: possible
1076
+ :consequence: major
1077
+ :threatens: GOAL-TRUSTED-CACHE
1078
+ :threatens: NEED-CORRECT-CACHE
1079
+
1080
+ The artifact directory is shared: `cargo build`, `cargo test`, `cargo bench` and `cargo run` all put a crate's executables at the same paths, and Nx stores what lies at the paths that `build` declares when its task ends ([[EVD-CARGO-ARTIFACT-WRITERS]]). [[ADR-TEST-AFTER-BUILD]] orders `test` after `build` within one command, and `bench` runs alone ([[DES-TARGETS]]). Four cases remain:
1081
+
1082
+ - **The files after a run.** A `test` or `bench` batch puts back, when it ends, the files of the command's builds that its commands link again, so that after a batched command that ran `build` and then `test`, or restored `build` and ran `test`, the artifact directory holds what `build` stored ([[DES-BATCH]], "Files that a test batch puts back"). Two cases remain, which the maintainer accepted with that decision on 20 November 2026 ([[ADR-TEST-AFTER-BUILD]]): a task that reads such a file while the tests run, such as a continuous task or a script started beside the command, gets the executable of `cargo test`; and where tasks run on their own, as with `--batch=false`, the artifact directory holds the executables of `cargo test` after such a command, as plain `cargo build && cargo test` leaves them, until the next `build`, run or restored, puts its own back, so that a task outside the plugin that depends on `build` and starts after the `test` runs the test build and, where it is cached, stores what it made of it ([[EVD-BATCH-FILES-ON-DISK]]). The same holds for `bench` and a `build` in the release profile. The cache entries of `build` are right in every case. Builds no longer replace each other's files: a `build` of the whole workspace and the compile of `napi-build` and `wasm-build` build in a stage ([[ADR-STAGED-BUILDS]]).
1083
+ - **Two `nx` commands at once.** A task graph orders tasks of one command only. A `cargo test` or `cargo run` of another `nx` command, or plain cargo, that writes a crate's executable while a `build` of the same crate ends can put its file under the key of `build`, and a `build` of another command can replace the executable that a running test is about to run. Neither the executor nor the guard can see another command.
1084
+ - **`run` with other options.** `cargo run` writes the executable of `build` byte for byte where its options are those of `build`. With other features or another profile, a `run` beside a `build` or a `test` of the same crate in one command can change what Nx stores for `build` or what the tests run. `run` is not cached, and nothing orders it.
1085
+ - **Files of one name that graph creation does not see.** Two crates of one artifact directory whose final artifacts have one file name write one file; cargo warns of an output filename collision when one call builds both, and the file is that of the crate it wrote last, so that the `build` of one crate can store the other's file, whatever the order of tasks ([[EVD-CARGO-ARTIFACT-WRITERS]]). The control plane decided on 14 November 2026, and nxr-ew8kb3 implemented, that graph creation compares these names and leaves the `build` of such crates uncached, and the `test` of those whose tests run such an executable, with a project warning that the keys hold, which names the crates and the file and says to rename one binary or library; graph creation does not fail, because cargo builds such a workspace, with a warning of its own, and the plugin must not make a valid Cargo workspace unusable ([[REQ-CARGO-UNCHANGED]]), while an uncached task stores no wrong entry ([[GOAL-TRUSTED-CACHE]], [[DES-OUTPUTS]], "Files of one name"). Graph creation compares the workspaces of every entry of the plugin, and counts artifact directories that lie one inside the other as one, since the folder of a triple or a profile in one can be the other; that also covers a triple that only the command line names. What graph creation cannot see, such as the projects of another installation of the plugin registered under another name, a check covers when a cached task starts, which fails the task. What neither sees remains: a crate that no `cargo metadata --no-deps` report names, such as a registry crate whose `dylib` cargo copies into the artifact directory as a member's dependency, and, for the check, a `test` whose crate's artifact directory lies outside the repository, which no metadata records.
1086
+
1087
+ The likelihood is that of the second and third cases, which need a habit, such as building in one terminal while testing in another; the fourth needs a registry crate built as a `dylib` with the name of a member's `cdylib`, and is rare. The consequence is a wrong executable restored from the cache. The control plane kept this rating on 14 November 2026. Closing the case of the members' files in nxr-ew8kb3 leaves it as it is, since the second and third cases decide it. [[ADR-TEST-AFTER-BUILD]] accepts this.
1088
+ :::
1089
+
1090
+ :::mara risk RISK-NX-RELEASE
1091
+ :mid: 01M7DBRA9111XN8TP1XDGJHS4C
1092
+ :title: Nx release does not drive the plugin as the release design reads it
1093
+ :status: accepted
1094
+ :likelihood: possible
1095
+ :consequence: moderate
1096
+ :threatens: REQ-RELEASE
1097
+
1098
+ [[DES-RELEASE]] rests on a reading of Nx 24.0.6 ([[EVD-NX-24-RELEASE]]) and, for versioning, on a run of version actions of this design through it ([[EVD-NX-24-VERSION-ACTIONS]]). The run confirmed that Nx takes a `release.version.versionActions` that the plugin's `createNodes` gives a project; that the version actions' `readDependencies` is Nx release's source of the dependents of a crate that Nx bumps on its own and of the order of release groups; that a failure while versions are worked out leaves every file on disk as it was; and that `afterAllProjectsVersioned` runs after the manifests are written and before the commit. It also showed ways in which Nx departs from the reading, which the design now takes into account: Nx decides two kinds of bump across release groups by the project graph or not at all (**Dependents** in [[DES-RELEASE]]); `nx release version` refuses a root `release.git`; and Nx formats each manifest that a run changes unless the version actions list it in their `manifestsToUpdate`.
1099
+
1100
+ Nx writes the changed files of a run one after another once every group is processed, with no way back. A review run on 14 November 2026, before the version actions checked that the files they change are writable, made one manifest read-only: the command exited with 1 and `EACCES` after ten other manifests had been written, which stayed changed and unstaged, without a commit or tag. The check now catches that case before Nx writes anything (**Writes** in [[DES-RELEASE]]); a failure that no check foresees, such as a full disk, or a file that another program changes or locks while Nx writes, can still leave files changed, and `git checkout` undoes them. The lockfile step runs after the writes by design, and a failure of cargo there leaves the files and the lockfiles updated before it changed in the same way (**Lockfile** in [[DES-RELEASE]]).
1101
+
1102
+ That Nx hands the `nx-release-publish` tasks of one release group to one batch, which [[EVD-NX-24-BATCHES]] showed for `nx run-many`, was run under `nx release publish` and `nx release` on 15 November 2026, before the publish target was built ([[EVD-NX-24-PUBLISH-BATCHES]]): with `preferBatch`, each release group's runnable tasks formed one batch, the groups in the order of the reported dependencies, `--projects` and `--groups` narrowed each batch to the selected tasks, and `NX_BATCH_MODE=false` ran every task on its own, which the design covers (**Without a batch** in [[DES-RELEASE]]). What remains is that a later Nx changes this; the compatibility rule for a new Nx major covers it ([[REQ-COMPATIBILITY]]).
1103
+ :::
1104
+
1105
+ :::mara risk RISK-REGISTRY-BEHAVIOUR
1106
+ :mid: 01M7DBRA91P6HC1WYADGEPJJYD
1107
+ :title: crates.io treats a release differently from the registry it was tested against
1108
+ :status: accepted
1109
+ :likelihood: possible
1110
+ :consequence: moderate
1111
+ :threatens: REQ-RELEASE
1112
+
1113
+ The measurements behind the release design used a local registry ([[EVD-CARGO-PUBLISH]]), and the tests use one too, because no test publishes to crates.io. crates.io checks more when a crate is uploaded, for example perhaps that a dev-dependency names a crate it has, and its index can take longer than the 60 seconds that cargo waits for an upload to appear, after which cargo stops before the crates that depend on it. A release that passed its dry run can then fail part way. The versions uploaded so far stay in the registry and cannot be uploaded again, so the rest has to be published by a second run, which leaving out existing versions allows ([[DES-RELEASE]]). How often this happens shows only in real releases.
1114
+ :::
1115
+
1116
+ :::mara risk RISK-UNCOMMITTED-PUBLISH
1117
+ :mid: 01M7G2R3TT6D60DVE2324A97BS
1118
+ :title: An older Cargo uploads uncommitted changes, which no later step takes back
1119
+ :status: accepted
1120
+ :likelihood: possible
1121
+ :consequence: major
1122
+ :threatens: REQ-RELEASE
1123
+
1124
+ Publishing leaves the question whether a tree with uncommitted changes may be published to cargo: the executor never passes `--allow-dirty` and checks no working tree of its own (**Credentials and tree** in [[DES-RELEASE]]). Cargo 1.91.0, the oldest Cargo that the plugin supports, does not refuse uncommitted changes where the Cargo workspace lies in a subfolder of the git repository, the usual layout of an Nx monorepo, while Cargo 1.97.1 to 1.100.0 refuse them there; 1.92 to 1.96 were not tried ([[EVD-CARGO-PUBLISH]]). On such a Cargo, `nx release publish` after an edit that was not committed, or after `nx release version` without git settings, which only stages its changes, uploads code that no commit holds, and a version once in a registry cannot be uploaded again: it can only be yanked and followed by a new version.
1125
+
1126
+ The maintainer accepted this on 15 November 2026 as a documented limit (nxr-rsaxx7): the release guide says what the runs showed and to commit before publishing, as `nx release` does by default. That is the mitigation; a check of the plugin's own with git and a newer minimum Cargo for publishing were rejected, because the plugin has nothing to do with git and a repository need not use it.
1127
+ :::
1128
+
1129
+ ## Evidence
1130
+
1131
+ :::mara evidence EVD-NXRUST-GAPS
1132
+ :mid: 01M78FHG7F71QFJZNFBAATR6N4
1133
+ :title: Gaps found in nxrust v0.3.0
1134
+ :status: accepted
1135
+ :supports: ADR-NEW-PLUGIN
1136
+
1137
+ Reading eddacraft/nxrust at v0.3.0 (last commit 22 October 2026) on 12 November 2026, in particular its product specification, its cache and toolchain design, `src/graph.ts`, `src/utils/cache-inputs.ts` and `plans/issues.md`, showed:
1138
+
1139
+ - Dev-dependencies are dropped from the graph, so a change in a dev-only workspace crate does not invalidate the dependent's cached tests.
1140
+ - The whole `Cargo.lock` is an input, so any lockfile change invalidates every crate.
1141
+ - There is no batching and no handling of feature unification.
1142
+ - `build.rs` `rerun-if-changed` paths and intermediate `.cargo/config.toml` files are not hashed.
1143
+ - The `cargo metadata` cache is in memory only, and the Cargo workspace must sit at the Nx root.
1144
+ - `build` restores `rlib` files into Cargo's `target/`.
1145
+
1146
+ This is a reading of source and documents, not a test of the plugin.
1147
+ :::
1148
+
1149
+ :::mara evidence EVD-NXRUST-BUILD-DEPS
1150
+ :mid: 01M78FHG7FKCEAGRQKJ36NF8WZ
1151
+ :title: Inherited ^build turned a 52-second test run into 40 minutes
1152
+ :status: accepted
1153
+ :supports: ADR-NO-RUST-BUILD-DEPS
1154
+ :supports: RISK-TARGET-DEFAULTS
1155
+
1156
+ nxrust's issue log records this as ISS-001, "Cross-language ^build inheritance amplifies cargo lock contention" (`plans/issues.md`, lines 8 to 31, in eddacraft/nxrust at commit 53572b2 of 22 October 2026). The measurement comes from nxrust's consumer workspace, eddacraft/anvil-001, pull request #1729. There, JS tests inherited `^build` across to the Rust crates, and `pnpm test` took 40m03s. After the script was split into `test:js && test:rust` it took 31 to 52 seconds, a 46-fold speedup. The entry states that the useful work was about 52 seconds and that the rest was cargo builds queued on the `target/` lock. The same figures are cited in `plans/modules/10-wasm-napi.aps.md`, under the cross-language `dependsOn` contract.
1157
+
1158
+ This is a secondary record: what was read, on 12 November 2026, is nxrust's account of the measurement, not the anvil-001 pull request itself. The measurement was not reproduced here.
1159
+ :::
1160
+
1161
+ :::mara evidence EVD-NX-24-INSPECTION
1162
+ :mid: 01M78FHG7F32NTNKGXVJT9QA2A
1163
+ :title: What Nx 24.0.6 declares about batching, inputs, cycles and affected
1164
+ :status: accepted
1165
+ :supports: ADR-ARTIFACT-TARGET-NAMES
1166
+ :supports: ADR-BATCH-EXECUTOR
1167
+ :supports: ADR-DECLARED-INPUTS
1168
+ :supports: ADR-ALL-DEP-KINDS
1169
+ :supports: ADR-COMPATIBILITY
1170
+ :supports: ADR-NO-RUST-BUILD-DEPS
1171
+ :supports: ADR-TEST-MODE-CHOICE
1172
+ :supports: RISK-TARGET-DEFAULTS
1173
+
1174
+ Inspection of the `nx` 24.0.6 package installed in this repository, on 12 November 2026:
1175
+
1176
+ - **`dependsOn`.** An object entry accepts `projects`, `dependencies`, `target`, `params`, `options`, `inputs` and `waitFor`, and no other property (`schemas/project-schema.json`). Nothing selects a configuration of the dependency's target.
1177
+ - **`^` dependencies.** An entry with `dependencies: true`, which is what `^build` stands for, adds the named target of every project the task's project depends on that has it. For a dependency without that target, the walk continues to that project's own dependencies. Nothing lets a plugin, or the project depended on, exclude itself (`tasks-runner/create-task-graph.js`).
1178
+ - **Batching.** An `executors.json` entry accepts `batchImplementation` and `preferBatch`. Without `--batch`, the scheduler batches a task only when its executor sets `preferBatch`. It forms one batch per executor, from the runnable tasks of that executor and the tasks of the same executor that depend on them (`tasks-runner/tasks-schedule.js`).
1179
+ - **Custom hashers.** The `hasher` entry and its types are marked "deprecated: Use target inputs instead. This will be removed in Nx 25".
1180
+ - **Affected.** `affected.legacy` in `nx.json` is described as "Select every task of each affected project, instead of only the tasks whose inputs a change reaches" and defaults to `false`, so selection by task inputs is the default.
1181
+ - **Cycles.** Running a command fails with "the task graph has a circular dependency" when tasks form a cycle, unless `NX_IGNORE_CYCLES` is set (`tasks-runner/run-command.js`). No check that rejects a cycle between projects was found.
1182
+ - **Target defaults.** A `targetDefaults` value can be an array of entries, each with a `filter` on `plugin`, `projects` or `executor`.
1183
+ - **Inputs.** Input kinds include `fileset`, `runtime`, `env` and `externalDependencies`.
1184
+ - **Plugin interface.** `createNodes` receives all matching files at once and may return `externalNodes`; `createNodesV2` is a deprecated alias. A plugin entry in `nx.json` accepts `include` and `exclude` lists beside `options` (`config/nx-json.d.ts`).
1185
+ - **Option overrides.** The options passed on the command line are part of a task's hash (`hasher/task-hasher.js`).
1186
+ - **CI detection.** `isCI()` reports CI when `CI` is set to anything but `false`, or when one of the variables that the common CI systems set is present, such as `GITHUB_ACTIONS`, `GITLAB_CI` or `BUILDKITE` (`utils/is-ci.js`).
1187
+
1188
+ This is a reading of type definitions, schemas and compiled source. It shows what Nx declares, not how it behaves in every case; behaviour is checked by the spikes named under the risks.
1189
+ :::
1190
+
1191
+ :::mara evidence EVD-NX-TARGET-DEFAULTS
1192
+ :mid: 01M7A0NA0X5XDW6MEQNS90EWC2
1193
+ :title: How Nx 24.0.6 lays target defaults over inferred targets
1194
+ :status: accepted
1195
+ :supports: RISK-TARGET-DEFAULTS
1196
+ :supports: ADR-NX-TARGET-NAMES
1197
+
1198
+ An experiment on 13 November 2026 with `nx` 24.0.6, Node.js 26.12.0, pnpm 12.18.0 and rustc 1.100.0, in a throwaway pnpm workspace outside this repository. A stand-in plugin, listed in `nx.json` by its package name, made projects of two crates, `app` and its path dependency `core-lib`, and gave each the `build` and `test` targets that [[DES-TARGETS]] and [[DES-INPUTS]] describe: no `dependsOn`, `cache: true`, a named input for the crate folder with its `^` form, an `env` input for `RUSTFLAGS`, a `runtime` input for `rustc -Vv`, and an executor with `batchImplementation` and `preferBatch`. The executor ran no cargo; it recorded what it received and wrote a file into the declared output. Beside the crates were a JS project whose `build` is a `package.json` script and one whose `build` came from a second stand-in plugin. Each variant of `targetDefaults` was read back with `nx show project <name> --json`. Runs used `nx run <project>:build --output-style=static`, with `NX_DAEMON=false` and `NX_CACHE_DIRECTORY` set to a folder that was emptied before each variant. The Nx sources read alongside are `project-graph/utils/project-configuration-utils.js`, and `target-defaults.js` and `target-merging.js` in `project-graph/utils/project-configuration/`.
1199
+
1200
+ - **Precedence.** Nx merges the targets of the plugins listed in `nx.json` first, then target defaults, then the targets of `project.json` and `package.json` files. A target default therefore overrides an inferred target, and a project's own file overrides the target default.
1201
+ - **Replaced, not merged.** An entry keyed `build` with `dependsOn: ["^build"]`, `inputs: ["default", "^default"]`, `outputs: ["{projectRoot}/dist"]` and `cache: false` replaced each of these four values on both crates. A field the entry does not set kept its inferred value. `options` were merged key by key, and the executor received the entry's option beside the inferred ones.
1202
+ - **Options.** An entry keyed `test` with `options: { passWithNoTests: true }` passed the option to the executor. With `additionalProperties: false` in the executor's schema, `nx run core-lib:test` failed instead, and the batch worker printed only an unhandled rejection with a `SchemaError`, naming neither the option nor the entry.
1203
+ - **Spread.** A list containing `"..."`, such as `inputs: ["...", "{workspaceRoot}/.tool-versions"]`, kept the inferred entries in that place and added the others.
1204
+ - **Cache key.** With `inputs: ["default", "^default"]` from a default, `nx run core-lib:build --exclude-task-dependencies` ran with `RUSTFLAGS` unset and then with `RUSTFLAGS=-Copt-level=1`. The second run restored the first result from the cache, including the file written under the empty `RUSTFLAGS`. Without the entry, or with `"..."` in its list, the second run executed.
1205
+ - **Outputs.** With `outputs: ["{projectRoot}/dist"]` from a default, a second run after deleting the inferred output folder was a cache hit that restored no file. Without the entry the hit restored the file.
1206
+ - **Task graph.** With `dependsOn: ["^build"]` from a default, `nx run app:build` also ran `core-lib:build`. Both tasks reached the executor in one batch, and the task graph in the executor's context held the dependency.
1207
+ - **Filters.** Array entries with `filter.plugin` set to the JS stand-in's name, with `filter.projects` set to `["tag:lang:js"]`, `["!tag:lang:rust"]` or `["packages/*"]`, where the crates carried the tag `lang:rust`, or with `filter.executor` set to `nx:run-commands` all left the crates' targets as inferred. `filter.plugin` compares with the `name` a plugin module exports or, if it exports none, with its entry in `nx.json`. It matched no target from a `package.json` script, not even as `nx/core/package-json`: Nx records a source plugin only for targets from the plugins listed in `nx.json`.
1208
+ - **Key precedence.** A key naming the target's executor is chosen before the key naming the target, even when its value is empty. With an empty entry keyed by the stand-in's executor beside a `build` entry, the crates' `build` stayed as inferred and the JS `build` targets took the `build` entry. An entry that sets another `executor`, such as `@nx/js:tsc`, was dropped for targets with a different executor.
1209
+ - **What a plugin sees.** `createNodes` receives `targetDefaults` as written in `nx.json`, not the merged targets. `createDependencies` receives `context.projects` with the merged targets. The batch executor found the merged target in `context.projectsConfigurations` and the added dependency in `context.taskGraph`. Nx's resolver for target defaults, `readTargetDefaultsForTarget`, is exported only from `nx/src/devkit-internals`.
1210
+
1211
+ The stand-ins ran no cargo, so this shows how Nx merges, hashes and schedules targets of this shape, not what inherited builds cost in time.
1212
+ :::
1213
+
1214
+ :::mara evidence EVD-NX-24-PLUGIN-NODES
1215
+ :mid: 01M7F6Z60PVYPTBT2264KKH65C
1216
+ :title: Nx 24.0.6 rewrites the project nodes that a plugin in its own process returns
1217
+ :status: accepted
1218
+ :supports: DES-TARGET-DEFAULT-GUARD
1219
+ :supports: RISK-GUARD-HASH-PLAN
1220
+
1221
+ A reading of the `nx` 24.0.6 package that this repository installs (paths under `dist/src/project-graph/utils/`), and runs on 15 November 2026 with it, Node.js 26.12.0 and cargo 1.100.0 on Linux, through the plugin's test harness (`nx-rust/test/harness`) in copies of the fixtures `binary-tests` and `subfolder-workspace`, with `NX_DAEMON=false` and the plugin once in Nx's own process (`NX_ISOLATE_PLUGINS=false`) and once in a plugin worker, Nx's default. A temporary line in the plugin printed, in `createDependencies`, the `dependsOn` that the plugin had inferred for `test` beside the merged one.
1222
+
1223
+ - **No copy.** Nx merges a list without `"..."` by taking the new list itself, and a list with `"..."` by building a new list that holds the elements of both by reference (`mergeArrayValue` in `project-configuration/utils.js`). The objects in the plugin's lists end up in Nx's merged project configurations unchanged.
1224
+ - **Placeholders.** After merging the results of one plugin, or of the synthesis of target defaults, or of one of Nx's default plugins, Nx walks the merged targets of the projects that those results touched and, in each `dependsOn` and `inputs` list, replaces each project reference with a placeholder (`registerNameRefs` in `project-configuration/project-nodes-manager.js` and `name-substitution-manager.js`). It changes an element of a `projects` list in that list, so where the list is the plugin's own, the plugin's object changes. Once every layer is merged, Nx replaces each placeholder that it finds in the merged configurations (`applySubstitutions` there). A placeholder in a list that a later layer replaced is never visited.
1225
+ - **Which references.** In `dependsOn`: a string that does not start with `^` and is not the name of a target of the project, which Nx splits with its target-string parser against the projects then known (`splitTargetFromConfigurations` in `utils/split-target.js`) and replaces where the parser finds a project and a target: a reading as a target and configuration of the project itself comes first, then the longest project name, and without a match the part before the first colon; an object's `projects` string other than `*`, `self` and `dependencies`, even a glob pattern; and each string of an object's `projects` list that is no glob pattern, which `isGlobPattern` in `utils/globs.js` judges by the characters `* | { } ( ) [`. In `inputs`: an object's `projects` string other than `self` and `dependencies`, and each string of its `projects` list that is no glob pattern. Nothing else is renamed: not `outputs`, `namedInputs`, a string input or a `^` dependency.
1226
+ - **Which project.** A placeholder stands for the root of the project that has the name when the layer's results are merged, or else of the last project that had that name earlier; for a name that no project had yet, it waits, and the first project that later takes the name gives it its root. Each layer is merged before its placeholders are made, so the projects of the plugin's own results already carry the names that it gave them. At the end, a placeholder with a root becomes the final name of the project at that root, a `:target` part following as it was written, and one without becomes the name as written.
1227
+ - **Seen.** In `binary-tests`, with `targetDefaults: { test: { dependsOn: [{ projects: ["directory:rust"], target: "lockfile" }] } }` and the plugin in Nx's own process, the plugin's record of every crate's `test` held `{ projects: [<placeholder for directory:rust>], target: "lockfile" }`, while the merged `test` held the entry as written. Where an entry keeps the plugin's list with `"..."`, both share the object, so the final pass also wrote the name back into the plugin's record. In a plugin worker, the results cross to Nx as a copy and the plugin's record stayed as inferred.
1228
+ - **Renames.** In `subfolder-workspace`, where `rust/crates/model/project.json` names that crate `model-rs` and `api` declares `dependsOn = ["...", { projects = ["model"], target = "check" }]` for `check`, the merged `check` of `api` depended on `{ projects: ["model-rs"], target: "check" }` in both modes. With `targetDefaults: { check: { options: { quiet: true } } }`, the plugin warned in a worker that it could not tell which configuration changed the `dependsOn` of `api:check`, and in Nx's own process it did not, because the final pass had written `model-rs` into the plugin's record through the shared object. Once the plugin handed Nx a copy, it warned in both modes.
1229
+ - **The guard.** On 15 November 2026, the tests in `nx-rust/test/target-defaults.spec.ts` set up the configurations that the review of the plugin as of commit f03da7c ran, with the plugin in Nx's own process and in a plugin worker: in `subfolder-workspace`, with `model` renamed `model-rs` and `api`'s declared `dependsOn` for `check` naming `model` as a list of projects, as a `projects` string or as `model:check`, an entry `check: [{ filter: { projects: ["api"] }, inputs: ["default"] }]`, and the same entry with `dependsOn: []` where `api`'s declared inputs named `model`; in `binary-tests`, with `library` renamed `library-rs` and `app`'s declared `dependsOn` for `build` naming `library:check`, an entry filtered to `app` with `outputs: []`. On that commit, each test failed in both modes; the review saw `nx show projects` exit with 0 and only the warning that the plugin could not tell which configuration changed the target. With the references renamed as Nx renames them and each field judged on its own, each failed graph creation with the error that names the entry, and an entry that set only options drew nothing. Since nxr-yatbsx, these cases and those of an entry that writes out the dependency on the lockfile task run with the plugin in Nx's own process only, where a placeholder shared with the plugin's record would show; [[VER-TARGET-DEFAULT-GUARD]] names the cases that still run in both modes.
1230
+ - **Source of a target.** The synthesis compares an element's `filter.plugin` with the plugin that the source map of the specified plugins names for the target's `executor`, or else its `command`, unless Nx's default plugins give the target an executor or a command, in which case no `filter.plugin` matches (`resolveSourcePlugin` in `project-configuration/target-defaults.js`). A plugin that later gives the same executor does not take that over: Nx records a source for a value only where the value changes (`getMergeValueResult` in `project-configuration/utils.js`). In `subfolder-workspace`, with a plugin named `other` listed before nx-rust that gave `api` the target `check` with the cargo executor, `targetDefaults: { check: [{ filter: { plugin: "other" }, inputs: ["default"] }] }` replaced the inputs of `api:check` in both modes, and the plugin as of commit 2488ff9 and on `main` created the graph with only the warning that it could not tell which configuration changed the target. The same tests fail on that code where a crate's Cargo metadata set `cache = false` for `check`, another plugin gave the crate the tag `extra` and an entry filtered to that tag turned on caching: graph creation went on with the warning, and where the other plugin cached `check` itself, `nx run api:check` ran cargo and succeeded with caching on, because a table's `cache = false` was not among the reasons the executor reads. The synthesis reads a project's name from the default plugins, or else from the specified plugins, and its tags from both (`buildProjectNodesAndRootToName` there), which are the name and tags of the merged project, since target defaults give neither.
1231
+ - **Which key.** For each target, the synthesis tries the key of the target's executor, then the key of its name, then the glob keys, longest first, and takes the first key with an element whose `filter` matches; a key whose elements all fail their filters falls through to the next (`resolveTargetDefaultMatches` and `orderedMatchingKeys` in `project-configuration/target-defaults.js`, lines 294–329). Which key applies therefore depends on the target's source where an element filters on `plugin`. In `subfolder-workspace`, with the plugin `other` listed before nx-rust giving `api` a `check` with the cargo executor, and `targetDefaults` holding `"@convesoft/nx-rust:cargo": [{ filter: { plugin: "other" }, inputs: ["default"] }]` and `check: [{ filter: { projects: ["api"] }, inputs: ["default"] }]`, the plugin as of commit 0016c40 failed graph creation naming only the entry keyed `check`, in both modes. With the entry keyed by the executor keeping the inputs with `"..."` instead, the merged inputs of `api:check` kept the plugin's, so Nx had applied that entry and not the one keyed `check`.
1232
+ - **Extra targets.** A target that a `targets.<name>` table of the Cargo metadata defines is part of the plugin's node, and Nx lays `targetDefaults` over it as over any target that a plugin infers. In `subfolder-workspace`, where `api`'s table defined `e2e` with `executor = "nx:run-commands"`, `"e2e": { "cache": true }` gave the merged `e2e` caching, and `e2e: { inputs: ["default"], outputs: [] }` replaced the table's `inputs` and `outputs`; the plugin as of commit 0016c40 failed graph creation for both, in both modes, and warned that it could not tell which configuration changed `e2e` where another plugin turned on its caching. A table in the `command` form gives the plugin's node no executor, and Nx gives the target `nx:run-commands` (`resolveCommandSyntacticSugar` in `project-configuration/target-merging.js`), so that the plugin's record and the merged target differed in their executor and the plugin compared nothing.
1233
+ - **Other layers.** Nx merges a later node's target into the target before it where at most one of them names an executor, or both name the same, and a list without `"..."` then replaces the earlier list; a target with another executor, or a `command`, replaces the earlier target whole (`mergeTargetConfigurations` and `isCompatibleTarget` in `project-configuration/target-merging.js`, lines 318–334 and 510–534). Runs on the same day, with `NX_DAEMON=false`: in `subfolder-workspace`, a plugin listed after nx-rust whose node gives `api` the target `check` with `inputs: ["default"]` and no executor, or with the cargo executor, left `api:check` with the cargo executor and the inputs `["default"]`, in both modes; so did a `project.json` in `rust/crates/api` written by hand, and the `nx` property of a `package.json` there that the root `package.json`'s `workspaces` enrols. In each, `nx run api:check` succeeded; after a `compile_error!` was added to `model`, which `api` depends on, the next `nx run api:check` was restored from the cache with exit status 0 and no cargo call, while `--skip-nx-cache` failed in cargo, as the same run does without the other layer. In `crate-shapes`, such a plugin's `outputs: []` on `cli`'s `build` left the executable missing after a cache hit, which Nx restores without it. The plugin as of commit 0016c40 reported nothing in each without `targetDefaults`; with the three empty entries that `nx add` writes, it warned that it could not tell which configuration changed the inputs of `api:check`, at graph creation and at the task's start, and the cache hit followed all the same. The same node from a plugin listed before nx-rust left the plugin's inputs, which replace it. The real `@nx/jest` 24.0.6, in a folder with a `package.json` that the `workspaces` enrol and a `jest.config.js`, infers `test` with `command: "jest"` (`src/plugins/plugin.js`, line 162): listed after nx-rust, it replaced `api:test` whole, so that the task ran `nx:run-commands` and no cargo, while the target kept the plugin's metadata, which only the plugin's executors read; listed before, the plugin's `test` replaced it whole. So only a node without an executor, or with the plugin's own, and a folder's `project.json` or `package.json`, change the lists of a target that still runs the plugin's executor. Graph creation sees no source map, but its rebuild gives what the folder's files do, so it can tell their changes from those of another plugin.
1234
+ - **What a list means.** The guard reads a target's inputs as the JS helpers of `dist/src/hasher/task-hasher.js` in Nx 24.0.6 expand them, which is not where Nx hashes them (below). `getNamedInputs` (lines 137–143) gives a project the named inputs `{ default: [{ fileset: "{projectRoot}/**/*" }], ...nxJson.namedInputs, ...project.namedInputs }`, so a project's own definition replaces that of `nx.json` whole. For a target without `inputs`, the helpers read `DEFAULT_INPUTS` (lines 128–136), `default` of itself and of its dependencies. `splitInputsIntoSelfAndDependencies` (lines 173–240) keeps `^name`, `{ input, dependencies: true }` and `{ input, projects }` for the dependencies and other projects, which read those projects' named inputs, and expands the rest with `expandSingleProjectInputs` (lines 247–279): a string that the named inputs hold stands for its definition, recursively, any other string is a file set, and an object with `fileset`, `env`, `runtime`, `externalDependencies`, `dependentTasksOutputFiles`, `workingDirectory` or `json` stays as it is. `filterUsingGlobPatterns` (from line 284) puts all of a project's own file sets into one list in which each pattern that starts with `!` excludes from every positive one, so that in these helpers a negated pattern anywhere among them, also inside a named input, leaves files out. These helpers are not what hashes a task: `InProcessTaskHasher` delegates to `NativeTaskHasherImpl` (`task-hasher.js`, about line 77), which hands `nx.json` and the project graph with its unexpanded inputs to the native `HashPlanner` (`native-task-hasher-impl.js`, line 37) and plans with `getPlansReference` (lines 72–74). The guard's reading is therefore an approximation of the native plan. In `subfolder-workspace` on 15 November 2026, with the plugin as of commit ce7a20e, the review saw a plugin listed after nx-rust that gave `api`'s `check` the inputs `["...", "!{projectRoot}/src/**/*"]` keep every inferred entry, and `nx run api:check` restored as a success after a `compile_error!` in `api/src/lib.rs`, while `--skip-nx-cache` failed; and the same for a plugin that gave `api` the named input `default` as `["{projectRoot}/Cargo.toml"]`, in both modes. With `@nx/js/typescript`, `@nx/jest/plugin` and `@nx/oxlint` 24.0.6 listed after nx-rust for `api`'s folder, which held a `package.json` that the root `package.json`'s workspaces enrol, a `tsconfig.json`, a `jest.config.js` and an `.oxlintrc.json`, the merged project kept the plugin's named inputs (only `default`, which the plugin defines), `lint` became `@nx/oxlint:lint` and `test` `nx:run-commands` with `jest`, `typecheck` and `nx-release-publish` were added, and `build`, `check`, `fmt` and `fmt-check` kept the plugin's executor and inputs, in both modes. A narrow re-check of the plugin as of commit 3e710b1, on 15 November 2026 with the real Nx 24.0.6 in both plugin modes, found where the native plan and the guard's reading differ; these are the review's runs, not repeated here. (1) A plugin listed after nx-rust that gave `api` `namedInputs: { narrow: ["!{projectRoot}/src/**/*"] }` and `check.inputs: ["...", { "input": "narrow", "dependencies": false }]` passed graph creation, because the guard expands an object input only where `dependencies` is absent, while Nx takes `false` as a self input and expands it: a change to the source left the key unchanged, and a `compile_error!` gave a cached success. (2) Where `model`'s `project.json` defined `selfFiles` and `model`'s targets read it in place of `default`, a later plugin that defined `default` for `model` as `["{projectRoot}/Cargo.toml"]` passed, because the guard keeps `api`'s `^default` as written and does not compare the definition in the project it names: a change to `model/src/lib.rs` left `api:check`'s key unchanged, with a cached success after a `compile_error!`. (3) A later plugin that added `"!{workspaceRoot}/rust/crates/api/src/**/*"` or `{ "fileset": "!{projectRoot}/src/**/*", "dependencies": true }` to `api:check` was refused, because the guard counts every added pattern that starts with `!`, while the native plan held the same file sets before and after and a change to the source still changed the key. (4) For a crate target without `inputs` from a later plugin, with a project-level `default` of `["{projectRoot}/Cargo.toml"]`, the native plan held `api:rust/crates/api/**/*`, and a change to the source still changed the key, which the JS helpers' expansion of `DEFAULT_INPUTS` through that `default` does not give ([[RISK-GUARD-HASH-PLAN]]).
1235
+
1236
+ So a plugin that compares the targets in `createDependencies` with what its `createNodes` returned has to hand Nx a copy; otherwise, in Nx's own process, its record depends on what the later layers did to its lists. And it has to give the references that it declares the names that Nx gives them before it compares: a reference to a project that a later layer renames reaches the merged graph with the new name in both modes. For a name that the plugin gave one of its own projects, that new name is the final name of the project at that root; for a name of another plugin's project, it depends on the names that projects had when each layer was merged, which `createDependencies` cannot see.
1237
+ :::
1238
+
1239
+ :::mara evidence EVD-NX-24-PLUGIN-ENTRIES
1240
+ :mid: 01M7WG05PX3BFMZEJB46K57FQE
1241
+ :title: How Nx 24.0.6 loads the plugin for each entry and calls its hooks
1242
+ :status: accepted
1243
+ :supports: DES-DISCOVERY
1244
+ :supports: DES-PROJECT-GRAPH
1245
+ :supports: RISK-UPSTREAM-CHANGES
1246
+
1247
+ A reading on 20 November 2026 (nxr-hjpc99) of the `nx` 24.0.6 package that this repository installs, paths under `dist/src/project-graph/`, checked the same day through the plugin's tests.
1248
+
1249
+ - **One copy per entry.** For each entry of `nx.json`, `loadSpecifiedNxPlugins` in `plugins/get-plugins.js` loads the plugin once, with the entry's index. `loadResolvedNxPluginAsync` in `plugins/load-resolved-plugin.js` imports the module, which Node's module cache makes one module per process, copies its properties into a new object with object spread, which reads each getter once, gives the copy the entry's `plugin` string as `name` where the module has none, and wraps the copy in a `LoadedNxPlugin` with the entry's options, `include` and `exclude` (`plugins/loaded-nx-plugin.js`). With plugin isolation, each entry gets a worker of its own, keyed by the entry, the root and the index (`getCacheKey` in `plugins/isolation/load-isolated-plugin.js`), which loads it the same way and holds only that entry (`plugins/isolation/plugin-worker.js`). A worker reads the requests that reach its socket together and dispatches each as it reads it, without waiting for the reply to the one before.
1250
+ - **How the hooks are called.** The copy's `createNodes` is a tuple of a glob and a function; `LoadedNxPlugin` calls the function as an element of the tuple (`createNodesImpl[1](...)`, so that the function's `this` is the tuple and not the copy), with the files and the entry's options, and the copy's `createDependencies` and `createMetadata` as methods of the copy: `plugin.createDependencies(this.options, context)` and `plugin.createMetadata(graph, this.options, context)`. The options are the value of the entry's `options` in `nx.json`, which the `LoadedNxPlugin` keeps, so every hook of an entry receives the same object, and `undefined` where the entry has none.
1251
+ - **Across graph computations.** Nx keeps the loaded plugins while the hash of `plugins` in `nx.json` stays the same (`getPluginsSeparated`), so the daemon passes an entry the same copy and the same options object in every computation. A change to `plugins` loads the entries again: in Nx's own process, every entry gets a new copy, while plugin isolation keeps the worker, and with it the copy, of each entry whose configuration, root and index are unchanged (`loadIsolatedNxPlugin`). Each computation calls each entry's `createNodes` once, with all the files it receives, in one synchronous loop over the entries (`createProjectConfigurationsWithPlugins` in `utils/project-configuration-utils.js`), and then `createDependencies` and `createMetadata` once each (`build-project-graph.js`), unless the daemon drops the computation after `createNodes` because a newer one overtook it (`daemon/server/project-graph-incremental-recomputation.js`). The daemon's computations can overlap: one can start while an earlier one is still in `createNodes`, and a worker can then receive both `createNodes` requests in one read and start both calls before the plugin lets go of the reports of the first computation ([[DES-METADATA-REPORT]]). The review of commit 404f1b6 of nxr-hjpc99 showed it with one entry, an edit to a Rust source and `nx show project app --json`, with the plugin's worker stopped until both requests waited at its socket: a guard that took two calls sharing those reports for two calls of one computation failed the newer computation, which Nx had started correctly, and the guard was removed.
1252
+ - **What tells the entries apart.** Nothing in the contexts: the contexts of `createNodes` and `createMetadata` hold `nxJsonConfiguration` and `workspaceRoot`, and that of `createDependencies` adds the merged projects, the external nodes and the file maps. `name` is the same for every entry of one plugin, so a key such as the workspace root and the entry's name cannot tell two entries apart. The options tell an entry only where it has them. The entry's `index` stays on the `LoadedNxPlugin` and does not reach the copy. The copy, on which Nx calls the later hooks, is therefore the only object of an entry that reaches its hooks, and the copy's own `createNodes`, read from the getter, links it to what that entry's `createNodes` found.
1253
+ - **Seen.** `nx-rust/test/plugin-entries.spec.ts` gave two entries of the plugin `include` lists that split `two-workspaces` between them and different `targetNames`. Each entry's projects had the target names of its own entry, and the graph had each entry's edges, in plugin workers, in Nx's own process, with the daemon and its plugin workers, and with the daemon running the plugins in its own process, there also in a second computation after a manifest changed. The reproduction of the review succeeded after the guard was removed.
1254
+
1255
+ So the link between an entry's hooks rests on how Nx calls them, which Nx documents nowhere: a later Nx that called a hook other than as a method of the copy, shared one copy between entries or split an entry's files between `createNodes` calls of one computation would break it, the last two undetected where the entries' options are one object or absent, and one that passed each call a new copy of the options would make every graph creation fail with the plugin's message ([[DES-DISCOVERY]], "Entries") until the plugin follows it. The end-to-end suite on that Nx is where such a change shows before it counts as supported ([[REQ-COMPATIBILITY]]).
1256
+ :::
1257
+
1258
+ :::mara evidence EVD-NX-OPTION-VALIDATION
1259
+ :mid: 01M7A93PSWDSC2D81P6MX8WZZ7
1260
+ :title: How Nx 24.0.6 checks, hashes and reports options of a batch executor
1261
+ :status: accepted
1262
+ :supports: ADR-UNKNOWN-OPTIONS
1263
+ :supports: DES-UNKNOWN-OPTIONS
1264
+ :supports: RISK-TARGET-DEFAULTS
1265
+ :supports: DES-TARGET-COMMANDS
1266
+
1267
+ An experiment on 13 November 2026 with the `nx` 24.0.6 package that this repository installs, Node 26.12.0, on Linux, in a throwaway workspace outside this repository, together with a reading of that package (paths below are under `dist/src/`). A stand-in plugin, listed in `nx.json` by its package name, made projects of two crates, `core-lib` and `app`, from their `Cargo.toml` files, tagged `lang:rust`, each with `build` and `test` targets that had `cache: true`, the crate's folder as their only input, an output folder and empty `options`. Their executor ran no cargo: it wrote the options it received, the task's overrides and the `targetDefaults` in its context into the task's output. It came in four variants, each with a schema that declared `features` (a list of strings) and `profile` (a string): with `batchImplementation` and `preferBatch: true`, or without them, and in each case once with `additionalProperties` unset and once with `additionalProperties: false`. `createNodes` and `createDependencies` recorded what they received, and could throw or warn. Unless a case says otherwise, commands ran with `NX_DAEMON=false`, `NX_TUI=false` and an emptied `NX_CACHE_DIRECTORY`: `nx run core-lib:test` and `nx run-many -t test build`, with `--output-style=static`, and with `--batch=false`, `--verbose` or flags such as `--coverage --ci` where stated, as well as `nx show projects` and `nx show project core-lib --json`. Hashes were read with `HashPlanInspector.inspectTask` and with `hashTask` of the in-process task hasher (`hasher/hash-plan-inspector.js`, `hasher/create-task-hasher.js`). The `targetDefaults` entry was `test: { options: { passWithNoTests: true } }` unless a case says otherwise. For the reviews of the same day, these were added: a `project.json` or `package.json` in a crate's folder, a `preTasksExecution` hook in the stand-in plugin, `nx show target core-lib:test --json`, `dependsOn` entries with `options` and `params` set to `"forward"` or left at `"ignore"`, a target that starts another through devkit's `runExecutor`, and an `args` option declared as a string, as a list of strings or as either. The executor computed for each unknown key whether it was a flag both in the task's own `__overrides_unparsed__` and in the `argv` that the hook recorded, and printed the result.
1268
+
1269
+ - **Where Nx checks options.** `combineOptionsForExecutor` (`utils/params.js`) merges a target's options, its configuration and the command line, and checks the result against the executor's schema. Nx calls it per task when the task runs: in the task's process (`command-line/run/run.js`, started by `bin/run-executor.js`) and in the batch process (`tasks-runner/batch/run-batch.js`). The batch process checks every task before it calls the batch implementation, outside its error handling. No caller runs while the graph is created.
1270
+ - **Closed schema, one task per process.** With `additionalProperties: false`, and without a batch implementation or with `--batch=false`, each `test` task failed with `'passWithNoTests' is not found in schema` in its own output, and the `build` tasks succeeded.
1271
+ - **Closed schema, batch.** With the batch implementation, `nx run core-lib:test` and `nx run-many -t test build` printed only Node's `UnhandledPromiseRejection: … The promise rejected with the reason "#<SchemaError>"` and failed every task of the batch, the two `build` tasks included, which had no unknown option. `--verbose` added nothing. `SchemaError` is not a subclass of `Error`. With the schema open, an entry that gave the declared `profile` the number 1 failed all four tasks in the same way. With `--batch=false`, and with the executor that has no batch implementation, only the two `test` tasks failed, each with `Property 'profile' does not match the schema. '1' should be a 'string'.`, and both `build` tasks ran.
1272
+ - **Open schema.** The option reached the implementation for a single task and the batch implementation, there as `inputs[taskId]`, among the task's options. The task's overrides were in `context.taskGraph` for the implementation for a single task and in the task graph that the batch implementation receives, and both had the `targetDefaults` of `nx.json` in `context.nxJsonConfiguration`.
1273
+ - **Command line.** `nx run-many -t test --coverage --ci` passed `coverage` and `ci` to every `test` task as overrides. With the closed schema and the batch implementation, every `test` task failed as above. Arguments after `--` arrived in the same way: `nx run core-lib:test -- --port 3000 serve` gave the options `port: 3000` and `_: ["serve"]`, as the same words without `--` did, and `__overrides_unparsed__` listed them without the `--`. When the command had `--`, Nx handed the task only the arguments after it, and dropped without a message the flags before it that Nx does not know itself, `--coverage` and also `--features=a`, which the schema declares: the task's header read `nx run core-lib:test --port 3000` (`withOverrides` in `command-line/yargs-utils/shared-options.js`). A `preTasksExecution` hook of the plugin received the command's `argv` with the `--` (`tasks-runner/run-command.js`). A value that the hook assigned to `process.env` reached the executor without a batch implementation with `NX_DAEMON=false` and with `NX_DAEMON=true`, for `nx run` and `nx run-many`, because Nx records such assignments and applies them to the `nx` process (`project-graph/plugins/loaded-nx-plugin.js`). A value returned from the hook did not arrive.
1274
+ - **Cache key.** Each task's hash plan held `core-lib:ProjectConfiguration` and the file `nx.json`, although the target's inputs named only the crate's folder. Both tasks of a project had the same value of `ProjectConfiguration`. It changed when the entry's value changed from `true` to `false` and when the entry's `options` were emptied, so the hash of `build` changed as well as that of `test`. Nx passes the native hasher, for each target, its executor, `inputs`, `outputs`, `options`, `configurations` and `parallelism`, and for the project its root, named inputs and tags (`toRustProjectGraph` in `native/transform-objects.js`). With a `project.json` that the inputs left out, a change there to `options` or `configurations` of `test`, or to the project's tags, changed `ProjectConfiguration` and the hashes of both tasks. A change to `metadata`, `cache` or `dependsOn` of `test`, or to the project's `metadata`, changed neither. Only these changes, on targets of the stand-in's executor, were tried. For an `nx:run-script` target, Nx passes `metadata.scriptContent` with the options. With a script `lint` in a `package.json` of the crate's folder, which Nx read and the inputs left out, changing the script from `echo a` to `echo b` changed the hashes of `build` and `test`. A change to `nx.json` that touched no target of the crates, adding `defaultBase` and a `lint` entry, made both tasks run again instead of being restored from the cache. The command line enters each task's hash through `hashCommand` (`hasher/task-hasher.js`): `--passWithNoTests` changed the hashes.
1275
+ - **What a plugin sees.** `createNodes` received `targetDefaults` as written in `nx.json`. `createDependencies` received the merged options, `{ "passWithNoTests": true }` on each `test`, as `nx show project core-lib --json` showed them, and its context type also offers `nx.json` (`project-graph/plugins/public-api.d.ts`), but no record of where an option came from. Nx keeps that record in `.nx/workspace-data/source-maps.json`, where an array entry gave `targets.test.options.passWithNoTests` the source `nx.json#targetDefaults.test[1]`, and resolves keys with `readTargetDefaultsForTarget`, which only `devkit-internals` exports. It tries the key named after the target's executor, then the target name, then glob keys longest first, and takes the first key with an entry whose `filter` matches, even an empty one. It evaluates `filter.projects` with `findMatchingProjects`, the matcher behind `--projects`, `filter.plugin` against the plugin that inferred the target and `filter.executor` against its executor (`project-graph/utils/project-configuration/target-defaults.js`).
1276
+ - **Graph creation.** An error thrown in `createDependencies` failed every command, `nx show projects` included, with `Failed to process project graph. The "<plugin>" plugin threw an error while creating dependencies: <message>`. A `console.warn` in `createDependencies` was printed by every command with `NX_DAEMON=false`. With `NX_DAEMON=true`, the default outside CI and Docker (`daemon/client/client.js`), it appeared only in `.nx/workspace-data/d/daemon.log`.
1277
+ - **Cache replay.** A cache hit printed the output that the task had produced, the executor's own line included.
1278
+ - **Narrowing.** An empty entry keyed by the executor's name beside the `test` entry, or the `test` entry as an array whose element had `filter: { projects: ["!tag:lang:rust"] }`, left the crates' `test` without options.
1279
+ - **Sources.** `nx show target core-lib:test --json` named, under `sourceMap`, the file or `targetDefaults` key behind each value of `options` and of each configuration. With `passWithNoTests: false` in `crates/core-lib/project.json`, the task received `false`, and `sourceMap` named that file, in three variants: beside the `test` entry, beside the `test` entry and an empty entry keyed by the executor, and beside a `test` entry whose `filter` excluded the crates. With `-c ci`, a value in the entry's `configurations.ci` won over the `project.json`'s `options`, and `sourceMap` named the entry for `configurations.ci.passWithNoTests`. `configurations.ci` from the entry and from `project.json` merged key by key, and a `defaultConfiguration` in `project.json` selected the configuration in a batch as `-c` does. Nx read a crate's `package.json`, and took the option from its `nx.targets`, only when the package manager's workspaces listed it or a `project.json` lay beside it, and then put `metadata.js` on the project. A call took about 0.25 s with the daemon and 0.35 s without, in this small workspace.
1280
+ - **Forwarded options.** Nx gives a dependency task the dependent task's `options` and active configuration when the `dependsOn` entry has `options: "forward"`. It gives the command's overrides only with `params: "forward"`, and otherwise sets `__overrides_unparsed__` to an empty list (`createTaskOverrides` in `tasks-runner/create-task-graph.js`). With `options: "forward"` and the `test` entry setting `passWithNoTests`, `core-lib:build` received `passWithNoTests` among its overrides with an empty `__overrides_unparsed__`. With `params: "forward"` and `--coverage`, `build` received `coverage` and `["--coverage"]`. With both forwarded, `build` received both, and only `--coverage` in its list. With a plain `dependsOn`, `build` received no override. Across these cases, batched and unbatched, with `NX_DAEMON=false` and `true`, a key was a flag in both the task's own list and the recorded `argv` exactly when the user had typed it, also after `--`; a target started in code is the exception below. With `test` configured with `coverage`, `nx run core-lib:test -- -- --coverage` gave the overrides `_: ["--coverage"]` and the list `["--", "--coverage"]`, and the option kept its configured value. Spellings: `--pass-with-no-tests` arrived as the key `pass-with-no-tests`, `--no-coverage` as `coverage: false`, `--coverage=false` as the string `"false"`, and `-x` as `x`.
1281
+ - **Started in code.** Devkit's `runExecutor` turns the options that its caller passes into overrides for the invocation it starts, an `__overrides_unparsed__` included. It passes the caller's context on unchanged, task graph included, so the started target gets no graph task of its own. It calls the target's single implementation, also for an executor that has a batch implementation (`command-line/run/run.js`). The started invocation's options are merged in this order: the target's options, which include `targetDefaults`; the configuration it runs with, which is the one the caller names or else the target's `defaultConfiguration`; and what the caller passes (`runExecutorInternal` there, and `combineOptionsForExecutor`). In each configuration below, a target `call` started `build` or `run` through `runExecutor`, with `NX_DAEMON=false` and with `NX_DAEMON=true`, and the outcome was the same in both:
1282
+ - `call` depended on `build` with `params: "forward"` and passed `{ coverage: "from-code" }`, with `nx run core-lib:call --coverage`. The graph task that the started `build` found held `coverage: true` and `["--coverage"]`. The earlier two-record rule gave the command-line form here, and the three conditions gave the general form.
1283
+ - The same, with `{ coverage: true }` passed: the three conditions gave the command-line form.
1284
+ - The same, with nothing passed and `build` configured with `coverage: true`: the three conditions gave the command-line form.
1285
+ - `call` depended on `run` with `params: "forward"` and passed `{ args: "--from-code" }`, with `nx run core-lib:call -- --port 3000`. The started invocation held no `port`. The earlier rule forwarded the arguments, and the three conditions forwarded nothing.
1286
+ - From the review of 13 November 2026: the same, with `options.port: 3000` on `run`. The started invocation held `port: 3000` and `args: "--from-code"`, and the three conditions forwarded the arguments.
1287
+ - The same, with `port: 3000` in `configurations.ci` of `run`. The arguments were forwarded when the caller named `ci` and when `ci` was the `defaultConfiguration`, and not forwarded when only the command had `-c ci`.
1288
+ - `params: "forward"` with `nx run core-lib:call -- --bin server`: the arguments were forwarded.
1289
+ - From the next review: `call` with `options: { coverage: true }` depended on `build` with `options: "forward"` and `params: "ignore"`, and passed `{ coverage: true }`, with `nx run core-lib:call --coverage`. The graph task held `coverage: true` and an empty `__overrides_unparsed__`, and the conditions gave the general form.
1290
+ - From the same review: `call` depended on `run` with `params: "ignore"` and passed `{ args: "--from-code" }`, with `nx run core-lib:call -- --bin server`. The graph task's list was empty, and nothing was forwarded.
1291
+ - The conditions gave the general form and forwarded nothing in each of these configurations: a value of another type (`"true"` for `true`, `"3000"` for `3000`); a different configured value; `--log-level` on the command line against `logLevel` passed in code; positional `-- serve`; and a caller that did not depend on the started target.
1292
+ - Ignoring. Twenty configurations were run: a caller running as a single task or in a batch; depending on `build` or `run` with `params: "forward"`, with `params: "ignore"` or not at all; and `build` with and without a batch implementation. In each, the started invocation received `fromCode: true`, which its schema did not declare, ran, printed its line, and the command succeeded. With a caller running as a single task, the line was part of the caller task's output and came back on a cache hit. With a caller running in a batch, the line was printed under the caller's header while it ran, but the cache hit replayed only the output that the caller's batch implementation returned.
1293
+ - **Inherited records.** With `nx run core-lib:test -- --port 3000`, a `build` task that `test` depends on, also as a continuous task, had the hook's record of `--port 3000` in its environment but an empty `__overrides_unparsed__`. With `params: "forward"`, its list equalled the record.
1294
+ - **`args`.** `--args="--port 3000"` arrived as the string `--port 3000` when the schema declared a string. When the schema allowed a list of strings, alone or as an alternative, it arrived as `["--port 3000"]`, and Nx split a string on commas, so `--args="--name 'a b',c"` became `["--name 'a b'", "c"]`. A repeated `--args` arrived as a list, which a string schema rejected with `Property 'args' does not match the schema`. Quotes, backslashes, an empty pair of quotes, `|`, `;`, `>` and `&&`, and an unterminated quote all arrived unchanged within the string. A value that looks like a number arrived as a number, which the string schema rejected: `--args=3000`, `--args="3000"`, `--args="'3000'"`, and `--args="1e3"` as `1000`. `--args=" 3000"` and `--args="3000 "` arrived as strings, `--args=true` as the string `true`, and `-- 3000` gave the task the list `["3000"]`. `--args --port 3000` without `=` gave `args: true`, which every schema rejected. Arguments after `--` that matched a declared option were checked as that option: `-- --profile` and `-- --profile 1` failed with `Property 'profile' does not match the schema`, while `-- --bin server --port 3000` arrived as `bin: "server"` and `port: 3000`. `-c ci` together with `--` kept the configuration.
1295
+ - **Recomputing the source.** Two reviews of a design that recomputed from the executor's context which file or `targetDefaults` key had supplied an option found cases in which it named the wrong one. Reproduced here:
1296
+ - a `project.json` that overrode the entry, also beside an empty entry keyed by the executor or under a `filter` that excluded the entry;
1297
+ - a value in the entry's `configurations.ci` that won over the `project.json`'s `options` under `-c ci`;
1298
+ - a list assembled from two sources: the entry's `reporters: ["a"]` and the `project.json`'s `reporters: ["...", "b"]` gave `["a", "b"]`, and `sourceMap` named a source per element;
1299
+ - a requested configuration that the target lacks: `-c missing` ran with the `defaultConfiguration`;
1300
+ - options forwarded from a dependent task.
1301
+
1302
+ The second review also named entries that Nx applies only to targets from a matching plugin or with a compatible executor. Nx records the plugin that inferred a target only in its source maps, and drops an entry that names another executor ([[EVD-NX-TARGET-DEFAULTS]]). The executor's context holds the merged target and `nx.json`, but not Nx's record of sources, and the options it receives no longer show which source gave them.
1303
+
1304
+ - **Known options.** An entry that set `features` replaced the `features` that the stand-in had inferred for `test`.
1305
+ - **Conversion.** `coerceTypesInOptions` (`utils/params.js`) converts string values from the command line by the type that the schema declares for the option. This was read, not tried.
1306
+
1307
+ The stand-ins ran no cargo, so this shows how Nx checks, hashes and reports options for an executor of this shape, not what the plugin's executor will print. Other Nx versions were not tried.
1308
+ :::
1309
+
1310
+ :::mara evidence EVD-NX-24-INPUT-SEMANTICS
1311
+ :mid: 01M7A0X81J8XAG79EE2DFXFEZD
1312
+ :title: How Nx 24.0.6 evaluates runtime inputs, selects affected tasks and hashes a cycle
1313
+ :status: accepted
1314
+ :supports: ADR-WORKSPACE-ROOT
1315
+ :supports: ADR-TEST-MODE-CHOICE
1316
+ :supports: ADR-ALL-DEP-KINDS
1317
+ :supports: DES-INPUTS
1318
+ :supports: RISK-NX-INPUT-SEMANTICS
1319
+
1320
+ Experiments on 13 November 2026 with `nx` 24.0.6, the version this repository installs, cargo and rustc 1.100.0, rustup with the toolchains 1.97.1, 1.98 and 1.100.0, Node 26.12.0 and git 2.56.0, on Linux x86-64 with bash as `/bin/sh`. The throwaway workspace lay outside this repository and had the default task-based affected. It held two Cargo workspaces: `rs`, whose `rust-toolchain.toml` selects 1.98, with the members `a`, `b` and `d`, where `b` depends on `a`, `a` has `b` as a dev-dependency and `d` depends on `b`; and `rs2`, with the member `c` and no toolchain file. A local plugin made each crate a project, with an edge for every dependency kind from `cargo metadata --no-deps`, and gave it two cached targets with the inputs of [[DES-INPUTS]]: the crate's folder as a named input and `^` over it, the workspace's `Cargo.toml` and `rust-toolchain.toml`, the runtime input `cd <workspace> && rustc -Vv`, a runtime input running a Node script that logged each evaluation with its working directory, `$0` and environment, and one `env` input. `probe` (`nx:run-commands`) logged `NX_TASK_HASH`. `test` used an executor with `batchImplementation` and `preferBatch: true` that ran `cargo test` once per Cargo workspace and logged its environment. The commands were `nx run-many -t probe --skip-nx-cache`, also with `-p` for subsets and from a crate's folder, `nx run-many -t test` with and without `--batch=false`, `nx affected -t probe --base=main --head=HEAD --explain=stdout` and `nx affected -t test --base=main --head=HEAD --skip-nx-cache` with and without `--batch=false`. Each case ran with `NX_DAEMON=false` and again with `NX_DAEMON=true`, the daemon started by `nx daemon --start` with variables that later commands did not set. Both modes gave the same results and the same hashes:
1321
+
1322
+ - **Evaluation.** Nx evaluated a runtime input once per task, not once per run: four tasks with the same command gave four evaluations. Every run evaluated it again, also when the daemon reused its cached project graph, and a changed output of the command, read from a file outside the workspace, changed the hashes of the next run.
1323
+ - **Shell and folder.** The command ran through `sh -c` (`$0` was `sh`), in the repository root, also when `nx` was started in a crate's folder. `cd rs && rustc -Vv` worked. The hash of `a` was the same with and without `RUSTUP_TOOLCHAIN=1.98`, that of `c` was not, and `RUSTUP_TOOLCHAIN=1.97.1` changed every hash: the toolchain file of the folder the command changed into applied.
1324
+ - **Environment.** The command saw the environment of the `nx` command. Variables that only the daemon's process had were not visible to it, and a `PATH` with another `rustc` in front changed the hashes under the daemon too. Nx added the dotenv files it loads for the task: a variable set in `rs/d/.env` reached the command of `d` only, one in a root `.env.test` reached the commands of `test` tasks, and a value set in the shell won over both, unless it equalled a root file's value (see the load order below). With `RUSTUP_TOOLCHAIN=1.97.1` in `rs/d/.env`, the hash of `d` differed from that of a run with the same file and `NX_LOAD_DOT_ENV_FILES=false`, and the hashes of `a` and `b` did not change; with `1.98` in that file, the two runs gave the same hash.
1325
+ - **Batches.** Nx hashed each task of a batch with that task's environment, but started the batch process with the environment of the `nx` command and the root `.env`, `.env.local` and `.local.env` only (`getEnvVariablesForBatchProcess` in `tasks-runner/task-env.js`). With `NX_RUST_TEST_MODE=full` in `rs/d/.env` or in a root `.env.test`, and the variable unset in the shell, the runtime input printed `full` while the batch process had no value; with `--batch=false`, each task's process had `full`. A value in the root `.env` reached both. Root files that apply to every task still gave a mismatch: with `NX_RUST_TEST_MODE=full` in `.env.local`, `affected` in `.local.env` and nothing in the shell, every runtime input printed `full` and the batch process had `affected`. With `affected` in the shell and in `.env` and `full` in `.env.test`, the runtime inputs printed `full` and the batch process had `affected`. Without dotenv files, batched and unbatched runs restored each other's results, four of four either way.
1326
+ - **Load order.** As read in the installed source (`utils/dotenv.js`, `tasks-runner/task-env.js` and `tasks-runner/task-env-paths.js`): at start, Nx loads `.local.env`, `.env.local` and `.env` from the repository root into its own environment, in that order of priority and below the shell, and the batch process inherits that environment. For a task, Nx copies that environment, unloads each variable whose value equals the one the root `.env`, `.local.env` or `.env.local` gives it, and then loads the task's files with variable expansion; the first file to set a variable wins, and no file overrides a value still present. It reads the project's folder first and then the repository root. In each, the identifiers are `<target>.<configuration>`, `<non-atomized target>.<configuration>`, `<configuration>`, `<target>` and `<non-atomized target>`, as far as they apply, each read as `.env.ID.local`, `.env.ID`, `.ID.local.env` and `.ID.env`, followed by `.env.local`, `.local.env` and `.env`. Because the unloading compares values, a shell value equal to a root file's value is removed before the task's files load, and a task file can then supply another value.
1327
+ - **Affected.** `nx affected` selected tasks by changed files only. A commit changing a source file of `a` or of `b` selected `a`, `b` and `d`; one of `d` selected `d`, one of `c` selected `c`, a change of `rs/rust-toolchain.toml` selected `a`, `b` and `d`, and a new root `README.md` selected nothing. Without a changed file, a new value of the `env` input, `RUSTUP_TOOLCHAIN=1.97.1` or a new output of a runtime command selected nothing, while `nx run-many` found none of the four tasks in the cache. In each of these seven cases, `nx affected -t test` ran the same tasks batched and with `--batch=false`.
1328
+ - **Cycle.** The hashes of `a`, `b` and `d` stayed the same across runs of all three together and of each alone, in either order. A change in `a` or in `b` changed all three hashes, and undoing it restored them. No run reported a task cycle.
1329
+
1330
+ One evaluation of `rustc -Vv` took about 6 ms on this machine, and one of the Node script about 14 ms.
1331
+
1332
+ These results support [[ADR-WORKSPACE-ROOT]], [[ADR-TEST-MODE-CHOICE]], [[ADR-ALL-DEP-KINDS]] and the toolchain, environment and `^` inputs of [[DES-INPUTS]]. They contradicted an assumption of [[DES-TEST-MODE]] and [[DES-BATCH]] as first written: in a batch, the executor and cargo can run with other values than the key was computed with, through a per-task dotenv file, through the different priority of `.env.local` and `.local.env`, or through an unloaded shell value. A toolchain set in one crate's `.env` also shows that the tasks of one Cargo workspace need not share a toolchain. [[RISK-NX-INPUT-SEMANTICS]] records what remains. The workspace was a toy and ran on one machine, so this says nothing about the cost of per-task evaluation in a large workspace or about macOS.
1333
+ :::
1334
+
1335
+ :::mara evidence EVD-CARGO-NO-DEPS
1336
+ :mid: 01M78RC7T7182TG80N949GFTTC
1337
+ :title: What cargo metadata --no-deps reports, offline and without a lockfile
1338
+ :status: accepted
1339
+ :supports: ADR-METADATA-NO-DEPS
1340
+
1341
+ An experiment with cargo 1.99.1 on 12 November 2026. The workspace had two members, a path dependency between them, a path dependency on a crate outside the workspace, two registry dependencies, `nx` metadata tables and no `Cargo.lock`. Cargo ran with an empty Cargo home and `--offline`.
1342
+
1343
+ - `cargo metadata --format-version 1 --no-deps` succeeded and created no `Cargo.lock`. Adding `--locked` changed nothing.
1344
+ - The full report failed in the same setting, because it could not find the registry dependencies.
1345
+ - The `--no-deps` report listed the two members as packages, with their targets and crate types, and the workspace and package `metadata` tables. Each declared dependency carried its name, version requirement, kind, features and source, and a path dependency carried the absolute path of its folder. `resolve` was null. `workspace_root`, `target_directory` and `build_directory` were present.
1346
+ - The crate outside the workspace was not among the packages. It appeared only as the path in its dependent's entry.
1347
+ - Run in a crate that lies inside the workspace folder without being a member, the command failed with Cargo's message "current package believes it's in a workspace when it's not", which names both manifests and the remedies.
1348
+
1349
+ The workspace was a toy, so this says nothing about how long the call takes on a large one; [[EVD-METADATA-TIMING]] measures that.
1350
+ :::
1351
+
1352
+ :::mara evidence EVD-METADATA-TIMING
1353
+ :mid: 01M7AY6TM7M03TJ2XKFHTP6R4A
1354
+ :title: How long cargo metadata --no-deps takes on large workspaces, and what its report depends on
1355
+ :status: accepted
1356
+ :supports: ADR-NO-METADATA-CACHE
1357
+
1358
+ Measurements on 13 November 2026 on Linux x86-64 (AMD Ryzen 9 9950X3D, NVMe SSD with btrfs) with rustup 1.29.3, Node 26.12.0 and the `nx` 24.0.6 package of this repository, in throwaway folders outside it. A time is the wall-clock time of `cargo metadata --format-version 1 --no-deps` started in the workspace root through rustup's proxy, process start included: the median of 20 runs with a warm page cache (10 for cargo 1.98.1), and of 3 to 5 runs after the page cache of the workspace, `~/.cargo/bin` and `~/.rustup/toolchains` was dropped with `posix_fadvise`, which leaves the kernel's directory caches warm. The first call in zed and ruff installed the toolchain each pins; the timed runs came after. No CI runner was measured.
1359
+
1360
+ | Workspace (shallow clone) | Cargo | Members | Report | Warm | Cold page cache |
1361
+ | ------------------------- | ------- | ------- | ------ | ------ | --------------- |
1362
+ | polkadot-sdk `78ad8d1` | 1.100.0 | 598 | 3.6 MB | 180 ms | 198 ms |
1363
+ | polkadot-sdk `78ad8d1` | 1.98.1 | 598 | 3.6 MB | 233 ms | |
1364
+ | zed `48741fd` | 1.98.1 | 262 | 1.5 MB | 79 ms | 97 ms |
1365
+ | ruff `bfd67d0` | 1.99.0 | 55 | 0.3 MB | 13 ms | 27 ms |
1366
+ | a fixture | 1.100.0 | 2 | | 7 ms | |
1367
+
1368
+ - **A stored report.** For polkadot-sdk, reading the report back and parsing it took 10 ms, listing its 9,894 files and hashing its 603 manifests 18 ms, Nx's `hashWithWorkspaceContext` over its manifests 1 ms once Nx had hashed the files, and `cargo -V` through the proxy 4 ms.
1369
+ - **What the report depends on**, with cargo 1.100.0 in the fixture. It changed with a member's or the root manifest; with a member added through a glob; with whether `src/main.rs`, `build.rs`, `tests/*.rs`, `examples/*.rs` or `README.md` exist, also for a gitignored file, which Nx's file map leaves out; with `build.target-dir` in a `.cargo/config.toml` or `.cargo/config` above the workspace root or in the Cargo home's `config.toml`; with `CARGO_TARGET_DIR` and `CARGO_BUILD_BUILD_DIR`; with the Cargo version, as 1.89 reports no `build_directory`; and with the checkout's folder, as every path in it is absolute. A broken manifest of a path dependency outside the workspace failed the call, while a change of its version or dependencies left the report as it was. `Cargo.lock`, the contents of a source file and of `README.md`, a member's own `.cargo/config.toml` and `RUSTFLAGS` changed nothing. No `rustc` was started and nothing was written to the Cargo home.
1370
+ - **Nx.** Nx turns the daemon off in CI and in Docker unless `NX_DAEMON=true` (`daemon/client/client.js`), and without it every command calls each plugin's `createNodes` (`project-graph/project-graph.js`). The helpers that Nx's own plugins use to keep results on disk, `PluginCache` and `workspaceDataDirectory`, come from `@nx/devkit/internal`, not from the public `@nx/devkit`.
1371
+ :::
1372
+
1373
+ :::mara evidence EVD-NX-PROJECT-MERGE
1374
+ :mid: 01M7A0S43EXZZGRM5WND8Z0BBG
1375
+ :title: How Nx 24.0.6 merges two plugins' projects at one root
1376
+ :status: accepted
1377
+ :supports: RISK-MIXED-PROJECT-MERGE
1378
+ :supports: REQ-WORKSPACE-PROJECT
1379
+ :supports: REQ-PROJECT-NAMES
1380
+ :supports: ADR-PROJECT-NAMES
1381
+ :supports: DES-PROJECT-GRAPH
1382
+ :supports: REQ-INFERRED-PROJECTS
1383
+ :supports: REQ-METADATA-OVERRIDES
1384
+ :supports: DES-METADATA-TABLES
1385
+
1386
+ An experiment on 13 November 2026 with `nx` and `@nx/js` 24.0.6, TypeScript 6.0.3, pnpm 12.18.0, Node 26.12.0 and cargo 1.100.0 on Linux, together with a reading of the same `nx` package (`project-graph/utils/project-configuration-utils.js`, `project-configuration/project-nodes-manager.js` and `target-merging.js`, `plugins/package-json/create-nodes.js`).
1387
+
1388
+ The throwaway pnpm workspace, outside this repository, had a Cargo workspace at its root (`members = ["crates/*"]`) with three member crates: `napi-addon`, `spike-core`, and `spike-cli`, which had path dependencies on the other two. The folder of `napi-addon` also held a `package.json` named `@spike/napi-addon`, which `pnpm-workspace.yaml` listed (`crates/*` and `packages/*`), with the scripts `build`, `test` and `prepublishOnly` and with `nx.tags`. A JS package `@spike/web` in `packages/web` depended on it with `workspace:*`. The root `package.json`, named `spike-root`, had no `nx` key unless a case says so. A stand-in for this plugin, the only plugin in `nx.json` unless a case says so, ran `cargo metadata --format-version 1 --no-deps --offline` for each workspace root manifest. It returned one project per member, named after the crate, with tags, metadata and `build` and `test` targets that ran cargo; `build` set `cache`, `inputs`, `outputs` and `metadata.description`. It also returned a project named `cargo-workspace` at the workspace folder, with `fmt`, `audit` and `deny`. Its `createDependencies` returned, in this order, an edge from the workspace project to each member (`napi-addon`, `spike-cli`, `spike-core`) and then one for each path dependency (`spike-cli` to `napi-addon`, then to `spike-core`). Depending on the case, it named each end by the stand-in's own name or by the name that `context.projects` lists for the project at that root. Each case was read with `NX_DAEMON=false NX_CACHE_PROJECT_GRAPH=false pnpm exec nx graph --file=out/graph.json` and `nx show projects`, and one target was run with `nx run`.
1389
+
1390
+ - **Order.** Nx merges all projects returned for one root into one project. It merges the plugins listed in `nx.json` in their order, then target defaults, then its built-in `package.json` and `project.json` plugins, in that order. No position in `nx.json` puts a plugin after those two.
1391
+ - **Name.** A later layer replaces the name. A folder whose `package.json` Nx reads takes its name from that file (`nx.name`, or else `name`), and a `project.json` that sets a name overrides both, whatever the order in `nx.json`. A `project.json` without a name kept the earlier name. Of two plugins listed in `nx.json`, the later one's name won. Nx reads a `package.json` only when the package manager's workspaces list it or a `project.json` sits beside it, and the root `package.json` also when it has an `nx` key. A crate's `package.json` outside the workspaces left the crate's project, name and targets unchanged.
1392
+ - **Targets.** Targets with different names were all kept. By `isCompatibleTarget` in `target-merging.js`, two targets with one name are merged when either of them names no executor, or when both name the same executor and, for `nx:run-commands` and `nx:run-script`, the same command or script, or one of them none. A merge keeps the earlier target's settings and lets each setting of the later one replace its counterpart: a `project.json` target `build` with `executor: "nx:run-commands"` and only `inputs`, or with `inputs` and no executor, kept the cargo command, `cache`, `outputs` and metadata and replaced the list of inputs. Any other target of the same name replaces the earlier one, with its `cache`, `inputs` and `outputs`. Only the earlier target's metadata can remain, merged under the later target's when the later one has metadata of its own: a `project.json` `build` with another command and no metadata left nothing of the cargo target. A `package.json` script is a target with the executor `nx:run-script` and with metadata, so the scripts `build` and `test` replaced the cargo targets while the stand-in's `description` stayed in their metadata, and `nx run` of the merged project's `build` ran the script. Between `@nx/js/typescript` and the stand-in, the plugin listed later in `nx.json` won `build`, and the TypeScript `build` came with its own `dependsOn: ["^build"]`.
1393
+ - **Tags, implicit dependencies and metadata.** The tags of all layers were united and their implicit dependencies combined. Metadata was merged key by key: objects such as `targetGroups` were combined, lists under one key concatenated, and a plain value such as `description` replaced by the later layer's.
1394
+ - **Edges.** In `createDependencies`, `context.projects` is keyed by the merged names, and each entry carries its root. Nx adds a plugin's edges one at a time, in the order returned. An edge whose target was the crate name of a project that `package.json` had renamed was dropped without a message, and the edges around it were kept. An edge whose source was such a name failed graph creation with "Source project does not exist". Nx added none of the edges after it, while those before it stayed in its partial graph. When the root `package.json` renamed the workspace project, the invalid source came first and no edge of the stand-in was kept. With an edge from `napi-addon` to `spike-core` inserted after the three edges from the workspace project, those three were kept and the two after it were not. Edges whose ends were looked up by root were all present. A `dependsOn` entry that named the crate was rewritten to the merged name, and the JS package's `workspace:*` dependency became an edge to the merged project.
1395
+ - **Workspace project at the root.** Without a root `project.json` and without an `nx` key in the root `package.json`, the workspace project stood alone under the stand-in's name. With either, it merged into the root project and took that file's name. The root scripts `audit` and `lint` and a `project.json` target `fmt` replaced or joined the workspace targets by the rules above, and the merged project depended on every member.
1396
+ - **Collisions.** A crate and a JS package with one name in different folders made Nx fail with its own message, "The following projects are defined in multiple locations", which lists both folders and recommends a `project.json`. A lookup by root in `context.projects` finds only one of two projects that share a name. When the stand-in returned an edge with the missing end undefined, Nx failed with "Cannot read properties of undefined (reading '1')" instead.
1397
+
1398
+ For a crate folder that also is a JS project, no plugin listed in `nx.json` can set the project's name. [[REQ-PROJECT-NAMES]], [[ADR-PROJECT-NAMES]] and [[DES-PROJECT-GRAPH]] therefore name such a project by its `package.json` or `project.json`; until 13 November 2026 they named every project after its crate or its `name` override. For the review of 13 November 2026, the following were re-run in the same workspace, with `outputs` added to the stand-in's `build`: the target merges and replacements, both edge orders, the dropped edges, the `dependsOn` rewrite, the names given by `nx.name` with and without a named `project.json`, and the TypeScript `build`. The other outcomes are from the first run. The stand-in modelled the planned plugin; the plugin itself and other Nx versions were not tested.
1399
+ :::
1400
+
1401
+ :::mara evidence EVD-NX-MIXED-CONSUMER
1402
+ :mid: 01M7J4NJ5W34WWBCND0ZSB4ZN7
1403
+ :title: How Nx 24.0.6 connects a JS consumer to a crate that is also a JS package
1404
+ :status: accepted
1405
+ :supports: REQ-MIXED-PROJECTS
1406
+ :supports: DES-MIXED-PROJECTS
1407
+ :supports: ADR-MIXED-PROJECT-TARGETS
1408
+ :supports: ADR-NO-RUST-BUILD-DEPS
1409
+ :supports: REQ-NO-RUST-TASK-DEPS
1410
+ :supports: DES-LOCKFILE-HASHING
1411
+
1412
+ An experiment on 16 November 2026 with `nx`, `@nx/js` and `@nx/js/typescript` 24.0.6, TypeScript 6.0.3, Node 26.12.0 and cargo 1.100.0 on Linux, with the plugin as of commit b2063b0 loaded from its source into Nx's own process (`NX_DAEMON=false`, `NX_ISOLATE_PLUGINS=false`, `NX_CACHE_PROJECT_GRAPH=false`), in a copy of the fixture `mixed-folders` outside this repository. The copy had a root `package.json` and a `pnpm-workspace.yaml` that enrols `libs/rust/crates/addon`, the folder of the crate `napi-addon`, whose `package.json` names it `@mixed/napi-addon` (the fixture's `project.json` there was removed), and `apps/*`. A package `web` in `apps/web` depends on `@mixed/napi-addon` with `workspace:*` and defines, under the `nx` key of its `package.json`, a cached `build` that runs `echo` with `dependsOn: ["^build"]`. Nothing was installed and there was no `pnpm-lock.yaml`. `napi-addon` depends on `engine`, which its `project.json` names `rust-engine`, and the workspace project in `libs/rust` is `libs-rust`. Graphs were read with `nx graph --file=<file>`, task graphs with `nx run web:build --graph=<file>`, and hashes with the test harness's `inspect-workspace.cjs`, which calls the functions that `nx run` hashes with.
1413
+
1414
+ - **Edge.** The graph had an edge of type `static` from `web` to `@mixed/napi-addon`, which Nx derived from the `workspace:*` dependency, and the plugin's edges named the crates by their merged names, `@mixed/napi-addon` and `rust-engine`.
1415
+ - **The plugin's `build`.** Without scripts in the crate's `package.json`, the task graph of `web:build` held `web:build`, `@mixed/napi-addon:build`, the plugin's cargo build, and `libs-rust:lockfile`, which that build depends on, and nothing else.
1416
+ - **A script.** With the scripts `build` and `test` in the crate's `package.json`, both targets ran `nx:run-script`, while the plugin's `cargo` record stayed in their metadata beside the script's; `check`, `lint` and the other targets stayed the plugin's. The task graph of `web:build` held the script `build` and nothing else. With `targetDefaults` holding the empty entries keyed by the plugin's executors that `init` writes and `build: { dependsOn: ["^build"], cache: true }`, the script `build` took `^build`, and the task graph held `web:build`, `@mixed/napi-addon:build`, `rust-engine:build`, the plugin's cargo build, and `libs-rust:lockfile`. Without the entries keyed by the executors, graph creation failed with the guard's error for the crates' `build` targets ([[DES-TARGET-DEFAULT-GUARD]]).
1417
+ - **`includedScripts`.** With `"nx": { "includedScripts": ["artifacts"] }` beside the scripts `build`, `test` and `artifacts`, the crate kept the plugin's `build` and `test` and gained only `artifacts`.
1418
+ - **Another plugin.** With `@nx/js/typescript` listed after nx-rust with its `typecheck` and `build` options, a `tsconfig.json` and a `tsconfig.lib.json` in the crate's folder and the `main` of its `package.json` under the `outDir` of `tsconfig.lib.json`, the merged `build` ran `nx:run-commands` with `dependsOn: ["^build"]`, beside the TypeScript plugin's `typecheck`, `build-deps` and `watch-deps`, and the task graph of `web:build` held `web:build`, `@mixed/napi-addon:build`, `rust-engine:build` and `libs-rust:lockfile`. With `main` outside the `outDir`, the TypeScript plugin inferred no `build`. Listed before nx-rust, it left the plugin's `build` and added its other targets.
1419
+ - **Keys.** The hash plan of `web:build` held the files of `@mixed/napi-addon` and of `rust-engine` and the workspace's root `Cargo.toml`, through `web`'s `^default` and the crates' named input `default`, which the plugin defines as the crate's folder and its workspace's root manifest. It held no lockfile digest and none of the variables, toolchain or tool versions that the crates' own keys hold: with `RUSTFLAGS=-Cdebuginfo=0` the hash of `@mixed/napi-addon:build` changed and that of `web:build` did not.
1420
+ - **The lockfile task replaced.** With `libs/rust/project.json` defining `lockfile` with the command `echo replaced-lockfile`, the merged `lockfile` ran `nx:run-commands` and the graph showed no metadata on it, and graph creation passed without a message. `nx run @mixed/napi-addon:check --skip-nx-cache`, also with `--batch=false`, ran the `echo`, then cargo's check, and then failed the task with the message of the check after cargo ([[DES-LOCKFILE-HASHING]], "Post-check") that the digest which this command's lockfile task wrote is missing, which goes on to blame a change of `Cargo.lock` while the run went on. Nx stored no result. Why the executor took the replaced target for the lockfile task, rather than failing before cargo because the task has no dependency on it, was not examined. With a `package.json` named `rust-root` beside that `project.json`, outside the package manager's workspaces, whose script `lockfile` replaced the target instead, Nx failed the script's own task with `Could not find project "rust-root"`, and the crate's task did not run.
1421
+
1422
+ So the edge from a JS consumer to a crate that is also a JS package comes from Nx's own analysis of the consumer's `package.json`, and the consumer's `^build` runs whatever `build` the merged project ends up with, under that target's own `dependsOn`. A consumer's key follows the crate's files and those of the crates behind it, but not what only the crates' own keys hold. A replaced lockfile task makes the crates' cached tasks fail without storing a result. The plugin as of b2063b0 has no artifact targets yet, so neither `napi-build` nor `wasm-build` was part of these runs.
1423
+ :::
1424
+
1425
+ :::mara evidence EVD-WORKSPACE-PROJECT-NAMES
1426
+ :mid: 01M7A8AKF5NT40CMP6236AFA2V
1427
+ :title: How Cargo 1.100.0 and Nx 24.0.6 treat names for a workspace project
1428
+ :status: accepted
1429
+ :supports: ADR-WORKSPACE-PROJECT-NAME
1430
+ :supports: REQ-PROJECT-NAMES
1431
+ :supports: DES-PROJECT-GRAPH
1432
+ :supports: DES-METADATA-TABLES
1433
+
1434
+ Experiments on 13 November 2026 with cargo 1.100.0, `nx` 24.0.6 and Node 26.12.0 on Linux, in throwaway folders outside this repository, together with a reading of the same `nx` package. The Nx workspaces linked the `node_modules` of this repository, had a root `package.json` and listed one stand-in plugin in `nx.json`. Its `createNodesV2` matched `**/name.txt` and returned a project at that file's folder, named by the file's content, with targets `fmt` and `audit` that echo the folder. Commands ran with `NX_DAEMON=false NX_CACHE_PROJECT_GRAPH=false NX_NO_CLOUD=true NX_TUI=false`, and runs with `--output-style=static --skip-nx-cache`.
1435
+
1436
+ - **Cargo has no workspace name.** In a virtual manifest, `name` under `[workspace.package]` made `cargo check --offline` warn `unused manifest key: workspace.package.name`. `cargo metadata --no-deps --offline --format-version 1` reported `workspace_root` as an absolute path, and `[workspace.metadata.nx]` with its nested `project` table (`name`, `tags`, `targets.sqlx-prepare.command`) unchanged under the report's top-level `metadata`. For a root manifest with both `[package]` and `[workspace]`, the report carried `[package.metadata.nx]` on that package and `[workspace.metadata.nx.project]` at the top level.
1437
+ - **Cargo package names.** `cargo metadata` on a one-package manifest rejected the names `a.b`, `a:b`, `a/b`, `a+b`, `a b` and `a~b` ("characters must be Unicode XID characters (numbers, `-`, `_`, or most letters)"), `@a` (not a Unicode XID start character) and `1abc` (starts with a digit), and accepted `abc`, `a_b`, `a-b`, `Rust-WS` and `ü-crate`.
1438
+ - **Nx accepts any name.** The stand-in created projects named `rust`, `a.b`, `@ws/rust`, `a:b`, `a b`, `Rust-WS`, `rust+ws`, `ws/rust`, `cargo:ws`, `ü-rust`, `a,b`, `!bang`, `x*y`, `tag:foo`, `a#b`, `rust/` and `.dot`. `nx show projects` listed all of them, and for each one `nx run <name>:fmt`, `nx fmt <name>` and `nx show project <name> --json` reached that project. Nx checks only that a name is present and unique (`validateProject` in `project-graph/utils/project-configuration/target-normalization.js`).
1439
+ - **Patterns.** `nx run-many -t fmt -p <name>` ran exactly that project for each name except two: `-p 'a,b'` split into `a` and `b` and ran five projects, and `-p '!bang'` excluded that project and ran every other one. A pattern without glob characters that is not exactly a project name matches the names that contain it as a whole word, ignoring case and counting `-` and `@` as part of a word, and only when no name matches, a project folder: `-p Rust` ran `rust`, `@ws/rust`, `rust+ws`, `ws/rust` and `rust/` (`utils/find-matching-projects.js`). With a `:` in a name, `nx run` tries every split of the string against the graph and warns when more than one fits (`utils/split-target.js`); `nx run a:b:fmt` and `nx run cargo:ws:fmt`, which no other project made ambiguous, ran.
1440
+ - **Folders.** A project named `rust-workspace` in `rustdir/` was reached by `nx fmt rustdir`, `nx run rustdir:fmt`, `nx show project rustdir --json`, `-p rustdir` and `-p directory:rustdir`, and one named `services-billing` in `services/billing/` by `nx fmt services/billing` and `nx run services/billing:fmt`; `nx fmt ./rustdir` failed with "Cannot find project". When a name is not found, `nx run`, `nx <target> <project>` and `nx show project` fall back to the same pattern matching and accept a single match (`command-line/run/run-one.js`, `command-line/show/project.js`). Inside `rustdir/`, a bare `nx fmt` ran that project (`config/calculate-default-project-name.js`).
1441
+ - **Root.** In a second workspace with the stand-in's project `cargo-workspace` at the root, a project `sub-crate` in `sub/` and a root `package.json` named `exp-root-pkg`, `nx fmt` from the root, `nx fmt .`, `-p .` and `-p directory:.` each ran the root project. `nx show project . --json` named the root project `cargo-workspace` without a root `project.json` and without an `nx` key; `exp-root-pkg` with `"nx": {}` in the `package.json`, and also with a root `project.json` of `{}`; and `repo` with a root `project.json` that sets that name. In each of these cases the project kept `fmt` and `audit`. With a `project.json` of `{}` and a root `package.json` without a name, graph creation failed.
1442
+ - **Default names.** For the review, a second stand-in matched `**/ws.txt` and named its project by the agreed rule: the path from the root with each `/` replaced by `-`, `cargo-workspace` at the root, or the file's content when it had any. Projects in `services/billing/` and `services-billing/` both got `services-billing`, and projects at the root and in `cargo-workspace/` both got `cargo-workspace`. In both cases Nx failed with "The following projects are defined in multiple locations", listing the two folders.
1443
+ - **When Nx reads a `package.json`.** With that stand-in and the name `billing-override` set for `services/billing/`, the project kept `billing-override` after a `project.json` of `{}` was added to that folder with no `package.json` beside it, and took `@acme/billing` once a `package.json` of that name was added beside the `project.json`. Without the `project.json`, that `package.json` left `billing-override` in place, with or without an `nx` key, until the root `package.json` listed `services/*` under `workspaces`. At the root, `cargo-workspace` gave way to the root `package.json` name when the workspace patterns included `.`, through `"workspaces": ["."]` in that file or `packages: ["."]` in `pnpm-workspace.yaml`, and stayed when `pnpm-workspace.yaml` listed only `packages/*`. Nx therefore reads a `package.json` when the package manager's workspace patterns include it or when a `project.json` sits beside it, and the root `package.json` also when it has an `nx` key; a nested `package.json` with only an `nx` key is not read (`plugins/package-json/create-nodes.js`).
1444
+ - **Nx's default.** For a `project.json` without a name, Nx uses the last segment of its folder in lower case, and `.` at the root (`config/to-project-name.js`); read, not run.
1445
+ - **Checkouts.** The checkout of this repository in which the work was done is a folder named `t3-978a6461-ca0fb10813ae42be`, not `nx-rust`.
1446
+
1447
+ How often a workspace folder has the name of one of its own crates was not measured, and macOS was not tested.
1448
+ :::
1449
+
1450
+ :::mara evidence EVD-NX-FORMAT
1451
+ :mid: 01M78JWQAZK1MDJ6GC4M70ZCXX
1452
+ :title: nx format cannot run rustfmt in Nx 24.0.6
1453
+ :status: accepted
1454
+ :supports: ADR-NX-TARGET-NAMES
1455
+
1456
+ Inspection of the `nx` 24.0.6 package installed in this repository, and two experiments, on 12 November 2026:
1457
+
1458
+ - **A command, not a target.** `nx format:check` and `nx format:write` (alias `nx format`) are built-in commands. They run the workspace's one formatter over changed files, over `--projects` or over `--all`, and they run no targets (`command-line/format/format.js`).
1459
+ - **Two formatters, no hook.** The formatter is oxfmt or prettier, detected from configuration files or from the dependencies in the root `package.json`, oxfmt first. Any other formatter is an error; there is no plugin hook (`utils/formatters/`).
1460
+ - **A reserved name.** `format` is in the list of known commands that Nx checks before it treats the first argument as a target (`bin/init-local.js`). `nx format <project>` therefore runs the built-in command, never a target named `format`.
1461
+ - **prettier.** Before Nx calls prettier it keeps only the files whose extension or name is in `prettier.getSupportInfo()`, called without plugins. With prettier 3.10.1 that call does not list `.rs`; it does when a plugin that declares `.rs` is passed explicitly. A prototype prettier plugin that pipes a file through `rustfmt --emit stdout` (rustfmt 1.10.0) formatted and checked `.rs` files through the plain `prettier` CLI. So a rustfmt plugin for prettier is feasible, but `nx format` drops `.rs` files before prettier sees them.
1462
+ - **oxfmt.** Given a `.rs` file and a `Cargo.toml`, oxfmt 0.78.0 ignored the `.rs` file and reported the `Cargo.toml` as unformatted. Its configuration schema has no setting for plugins or external formatters. In a workspace that uses oxfmt, `nx format:write` therefore reformats `Cargo.toml` files and leaves Rust sources alone.
1463
+
1464
+ The prototype was not run through `nx format` itself; that Nx filters `.rs` out is read from its source, and that the filter excludes plugin languages was tested against prettier directly. Covering Rust in `nx format` would need Nx to pass the configured plugins to its filter, and would still not reach workspaces that use oxfmt.
1465
+ :::
1466
+
1467
+ :::mara evidence EVD-CARGO-NEW
1468
+ :mid: 01M7A66QH6W8544G03RW7GAX0G
1469
+ :title: What cargo new does inside a repository and a workspace
1470
+ :status: accepted
1471
+ :supports: DES-GENERATORS
1472
+ :supports: DES-DIAGNOSTICS
1473
+
1474
+ Experiments with cargo 1.100.0 (3acc79c0c 2026-11-05) on Linux, on 13 November 2026, in throwaway git repositories (`git init`, no commit) outside this repository. No folder pinned a toolchain.
1475
+
1476
+ - **A git repository inside the crate.** In a repository where `rust/` existed and `rust/crates/` did not, `cargo new rust/crates/core` created `.git` and a `.gitignore` inside the new crate. Where the parent folder existed, `cargo new direct` created neither. `cargo new --vcs none newparent2/a/b`, with no folder of that path present, created neither.
1477
+ - **Members.** In a workspace with `members = ["crates/*"]`, `cargo new --lib rust/crates/core` left the workspace manifest unchanged. `cargo new --bin rust/tools/cli` printed "Adding `cli` as member of workspace at …" and appended `"tools/cli"` to `members`, keeping the existing entry. In a workspace without a `members` key, `cargo new --vcs none --lib ws-nomembers/crates/a` added `members = ["crates/a"]`. With a workspace inside another workspace's folder, the crate was added to the nearer workspace only.
1478
+ - **Exclude.** Cargo reads an `exclude` entry as a path relative to the workspace root, not as a glob. In a workspace with `members = ["crates/*"]` and `exclude = ["vendor/*", "legacy"]`, `vendor/*` excluded nothing: `cargo metadata --no-deps --format-version 1` in a package at `vendor/v` that `members` did not list failed with "current package believes it's in a workspace when it's not". The path entry `legacy` did exclude: `cargo new --vcs none --lib legacy/old` still printed "Adding `old` as member of workspace", appended `"legacy/old"` to `members` and left `exclude` as it was. `cargo metadata` in `legacy/old` then reported the workspace root, so the explicit member overrode `exclude`. With `"legacy/old"` removed from `members`, it reported `legacy/old` as its own workspace root. Cargo 1.91.0 and 1.100.0 behaved the same, in a run on 13 November 2026 that the reviewer of nxr-eg9s2w repeated.
1479
+ - **Inheritance.** In a workspace whose `[workspace.package]` set `edition = "2021"` and `license = "MIT"` and which had `[workspace.lints.rust]`, the new manifest had `edition.workspace = true`, `license.workspace = true` and `[lints] workspace = true`. With `--edition 2024`, it had `edition = "2024"` and still `license.workspace = true`.
1480
+ - **Name.** `cargo new --vcs none --bin --name my-tool rust/crates/tool-dir` created the package `my-tool` in the folder `tool-dir`. Without `--name`, the package took the folder's name; for `core`, cargo warned that the name may be confused with the standard library's package.
1481
+ - **Outside a workspace.** `cargo new --vcs none --lib standalone-parent/s` wrote `edition = "2024"` and changed no other manifest. Inside the folder of a valid package without a `[workspace]` table, the new crate was its own workspace root, according to `cargo metadata`. When the enclosing package's manifest was invalid, cargo still created the crate and warned that compiling it may not work.
1482
+ - **An existing folder.** `cargo new --vcs none --lib rust/crates/ed`, run a second time, failed with "destination `…` already exists" and exit status 101, and changed nothing.
1483
+ - **Options.** `cargo new --help` lists `--vcs` (`git`, `hg`, `pijul`, `fossil`, `none`), `--bin` (the default), `--lib`, `--edition` (2015, 2018, 2021, 2024), `--name` and `--registry`.
1484
+
1485
+ Apart from the exclude bullet, only one Cargo version was tried, on Linux. The messages observed carried no error codes.
1486
+ :::
1487
+
1488
+ :::mara evidence EVD-CARGO-DIRECTORIES
1489
+ :mid: 01M7A6739R6CSCWVAQ2JJWDHF2
1490
+ :title: Where Cargo puts its two directories, and which versions report them
1491
+ :status: accepted
1492
+ :supports: DES-GENERATORS
1493
+ :supports: DES-DIAGNOSTICS
1494
+ :supports: DES-OUTPUTS
1495
+
1496
+ Experiments on Linux on 13 November 2026, in throwaway folders outside this repository, with `cargo metadata --no-deps --format-version 1`. No folder pinned a toolchain, and the older toolchains were already installed and selected with `cargo +<version>` under `RUSTUP_AUTO_INSTALL=0`.
1497
+
1498
+ - **Default.** Without configuration, cargo 1.100.0 reported `build_directory` and `target_directory` both as `<workspace>/target`, inside the workspace folder. For a crate that is its own workspace, that is a folder inside the crate.
1499
+ - **Template.** With `[build] build-dir = "{cargo-cache-home}/build/{workspace-path-hash}"` in a `.cargo/config.toml` above the workspace, cargo 1.100.0 reported a `build_directory` below the Cargo home (`~/.cargo/build/21/d5123ee45e798c`) and the same `target_directory` as before.
1500
+ - **Spelling.** In a copy of the `two-workspaces` test fixture, cargo 1.100.0 started in `tools/` reported both directories as `<repo>/tools/../target`, both for `target-dir = "../target"` in `tools/.cargo/config.toml` and for `CARGO_TARGET_DIR=../target`. With `"../target/"` it kept the trailing separator. With `target-dir = "out"`, where `tools/out` was a symbolic link to `../target`, a folder that did not exist, it reported `<repo>/tools/out`, and `cargo metadata` did not create the folder. Started at the repository root, the root workspace reported `<repo>/target`. Cargo thus joins a relative setting to the folder it belongs to, without resolving `..` or links.
1501
+ - **Versions.** For a one-crate package, the report of cargo 1.89 had no `build_directory` key, and the reports of cargo 1.97.1 and 1.100.0 had it. The other top-level keys were the same in all three: `metadata`, `packages`, `resolve`, `target_directory`, `version`, `workspace_default_members`, `workspace_members` and `workspace_root`.
1502
+
1503
+ Cargo's source settles where the field begins. It was added to `cargo metadata` by rust-lang/cargo pull request #15377, merged on 2 April 2025, while `build.build-dir` was unstable. In the Cargo that Rust 1.90.0 ships (rust-lang/cargo commit 840b83a, package version 0.91.0), `src/cargo/ops/cargo_output_metadata.rs` writes `build_directory` only when the unstable `-Zbuild-dir` flag is on, and leaves the key out otherwise; unstable flags work only on nightly. In the Cargo that Rust 1.91.0 ships (commit ea2d978, package version 0.92.0), it always writes the field, and Cargo's changelog lists the stabilisation of `build.build-dir` under 1.91. The report of a stable Cargo therefore has `build_directory` from 1.91 on. The source was read through GitHub, at the cargo commits that the `src/tools/cargo` submodule of rust-lang/rust names at the tags `1.90.0` and `1.91.0`. Cargo 1.90 and 1.91 were not run here, because no toolchain was downloaded.
1504
+ :::
1505
+
1506
+ :::mara evidence EVD-RUNTIME-INPUT-SCRIPTS
1507
+ :mid: 01M7WNEMK2SMVT1W9WM5JWK113
1508
+ :title: What Nx 24.0.6 does with a failing runtime input, what the variables of the toolchain command lost to multi-line values, and what the artifact folder input costs
1509
+ :status: accepted
1510
+ :supports: DES-INPUTS
1511
+ :supports: DES-TEST-MODE
1512
+
1513
+ Experiments on 20 November 2026 in nxr-aqgka5, with `nx` 24.0.6, Node 26.12.0, cargo 1.100.0 through rustup, GNU awk 5.4.1 and bash as `/bin/sh`, on Linux x86-64.
1514
+
1515
+ - **Nx.** In a throwaway workspace with two projects whose cached `nx:run-commands` targets printed `NX_TASK_HASH` and shared one runtime input, a script that logged each evaluation: one `nx run-many` evaluated it twice, once per task, in the repository root, although command and environment were the same. Output `OUT` on standard output and `STDERRTEXT` on standard error gave the same two keys with exit status 0 and 7, and another text on standard error gave other keys. Nothing of standard error showed on the terminal, with the daemon and without, and with `--verbose` and `NX_VERBOSE_LOGGING=true`. A variable whose values `a\nb` and `a\nc` differed only in their second line reached the command whole: a command that printed it gave two keys.
1516
+ - **The lines of `env`.** The toolchain command's former `env | grep -E '^CARGO_(PROFILE|TARGET)_' | grep -v '^CARGO_TARGET_DIR=' | LC_ALL=C sort` printed `CARGO_TARGET_X_RUSTFLAGS=--cfg=a` for both `--cfg=a\n--cfg=b` and `--cfg=a\n--cfg=c`, printed `CARGO_PROFILE_DEV_OPT_LEVEL=1` for a variable `OTHER` whose second line that was, and left out the line `CARGO_TARGET_DIR=x` of a profile variable's value. Cargo splits a flags variable at whitespace, line breaks included, so the first pair reaches the compiler differently under one key. awk's `ENVIRON`, with a backslash doubled and a line break written as `\n`, printed each variable whole on one line, and for single-line values without a backslash exactly what the pipeline printed; `gawk --posix` and `gawk --traditional` printed the same. `runtime-inputs.spec.ts` checks those lines, and `cache-keys.spec.ts` the keys that Nx's own hasher computes from them for `api:build`, `api:test` and `rust:doc` of `subfolder-workspace`: with the toolchain command put back to the pipeline, that test failed, the keys staying the same for the two flags variables and changing for `OTHER_FLAGS`, and with awk it passed. With cargo 1.91.0 as rustup's default, through a private `RUSTUP_HOME`, `runtime-inputs.spec.ts`, `target-triples.spec.ts`, `test-mode.spec.ts`, `caching.spec.ts`, `cache-keys.spec.ts` and the end-to-end suite passed as well.
1517
+ - **What Nx hashes of the output.** In the same workspace with one project, on 20 November 2026 in the review of nxr-aqgka5: `printf 'a\nb'`, `'a\nb '`, `'a\nb\n\n'`, `' a\nb'` and `'a\nb\t'` gave one key, so Nx trims the whitespace at both ends; `printf a; printf b >&2`, `printf b >&2; printf a` and `printf ab` gave one key, so it puts standard error after standard output, without a separator; `printf 'a\nb'` with a lone space on standard error gave the key of `'a\nb'`, so it trims each stream on its own; and a byte `\377` on standard output or standard error made the whole `nx` command fail with "invalid utf-8 sequence of 1 bytes from index 0". The reviewer of nxr-aqgka5 saw a value of a linker with a space at its end, which cargo does not find, share the key of the value without it where the variable came last, and saw the toolchain command print the same text for two values of a flags variable on a `PATH` that held cargo, Node, the linker, `env`, `grep` and `sort` but neither awk nor `od`, so that Nx restored the binary of the first value.
1518
+ - **The fallback without `od`.** Reading 16 bytes of `/dev/urandom` with the shell's own `read` and printing each with its own `printf` in a subshell with `LC_ALL=C` printed 32 hexadecimal digits, new at each run and with nothing on standard error, in bash, `bash --posix`, dash and BusyBox `sh` with an empty `PATH`, and printed `ff8041` for the bytes `\377\200A` in each; with `/dev/urandom` unreadable it printed the process ids and, where `date` existed, the time; the re-check of the review found that two runs in fresh process namespaces print the same process ids, so without `date` such runs repeat (nxr-ntvnds). Through Nx's own hasher in `subfolder-workspace`, on a `PATH` of links to the tools that the harness needs (`runtime-inputs.spec.ts`): without awk, without awk and `od`, and with the artifact folder script failing and `od` missing, two hashings of one state gave two keys of `api:build`; without `od` alone the key repeated and changed with the flags variable; and a linker value with a trailing space changed the keys of `api:build` and `api:test`.
1519
+ - **Cost.** With `hyperfine`, 40 runs each, in a copy of the `two-workspaces` fixture: starting Node took 12.5 ± 0.9 ms; Node loading the modules of `print-artifact-folders.js` 20.1 ± 1.4 ms, and loading `child_process` alone 14.2 ± 1.6 ms; `cargo metadata --no-deps --format-version 1` 6.6 ± 0.4 ms; the script 29.9 ± 1.9 ms and, run again, 28.8 ± 1.7 ms; the script through the runtime input's `sh -c` command 29.6 ± 1.9 ms; and the script with `NODE_COMPILE_CACHE` filled beforehand 30.4 ± 2.5 ms. Replacing the module that `directories.js` loaded for one function with that function left the loading time as it was.
1520
+
1521
+ So Nx gives a failing runtime input no voice and keys its task on whatever it prints, and the plugin's random value is the only way to keep such a task from being restored, while the reason can only show where the plugin's own executor runs. A key that took the lines of `env` lost the end of a multi-line value. The artifact folder input spends its time in Node and cargo, which no exact change of the script removes.
1522
+ :::
1523
+
1524
+ :::mara evidence EVD-RUSTUP-MISSING-TOOLCHAIN
1525
+ :mid: 01M7AN00P9TZ5VQQT8SSXTHC4V
1526
+ :title: What rustup 1.29.3 and Nx 24.0.6 do when a pinned toolchain is missing
1527
+ :status: accepted
1528
+ :supports: DES-METADATA-REPORT
1529
+ :supports: RISK-NX-INPUT-SEMANTICS
1530
+ :supports: ADR-GRAPH-NO-TOOLCHAIN-INSTALL
1531
+ :supports: DES-INPUTS
1532
+
1533
+ Experiments on 13 November 2026 on Linux x86-64 with rustup 1.29.3, whose proxies came first on `PATH`, and with `nx` 24.0.6, in throwaway folders outside this repository. A folder's `rust-toolchain.toml` named the toolchain `1.92.0`, which was not installed. Every command that could reach rustup ran with `RUSTUP_AUTO_INSTALL=0`, and rustup listed the same toolchains afterwards.
1534
+
1535
+ - **rustup's default.** Earlier that day, while the test fixtures were built and with the variable unset, a plain `rustup show active-toolchain` in a folder whose toolchain file named `1.91.0`, missing then, downloaded and installed that toolchain without asking. That case was not run again.
1536
+ - **Missing toolchain.** In the pinned folder, `cargo metadata --no-deps --format-version 1` and `rustc -Vv` each wrote nothing to standard output, wrote `error: toolchain '1.92.0-x86_64-unknown-linux-gnu' is not installed` and ``help: run `rustup toolchain install` to install it`` to standard error, and exited with status 1. So did `sh -c 'cd pinned && RUSTUP_AUTO_INSTALL=0 rustc -Vv'`, the form a runtime input takes, started in the parent folder with the variable unset.
1537
+ - **Folder.** In a workspace whose root pinned nothing, a member and a path dependency outside the workspace each pinned `1.92.0` in their own folder. `cargo metadata` started in the root folder succeeded, for the workspace and with `--manifest-path` naming the path dependency, while the same calls started in the member's and in the dependency's folder failed as above. The folder a command starts in decides which toolchain file applies, not the manifest it reads.
1538
+ - **Without rustup.** With the cargo and rustc 1.99.1 of the Arch Linux `rust` package first on `PATH`, which are no rustup proxies, both commands succeeded in the pinned folder with the variable set: cargo reported the package, and `rustc -Vv` reported 1.99.1. Such a toolchain ignores the toolchain file and the variable.
1539
+ - **Nx.** In a workspace whose cached `nx:run-commands` target had the runtime input `cd ../pinned && RUSTUP_AUTO_INSTALL=0 rustc -Vv` as its only input, `nx run` with the daemon off ran the task, succeeded and printed nothing about the failed command, and a second run restored the task from the cache. With `1.93.0`, also missing, pinned instead, the key changed. With runtime commands such as `echo A >&2; exit 1`, the key followed what the command wrote to standard error, and neither its exit status nor its text: `exit 1`, `exit 2` and `exit 0` after the same `echo A >&2` gave one key, and so did `exit 3` and `exit 4` without output.
1540
+ - **A value per evaluation.** With the runtime input `cd ../pinned && RUSTUP_AUTO_INSTALL=0 rustc -Vv 2>/dev/null || od -An -N16 -tx1 /dev/urandom`, three runs of the task gave three different task hashes, each a cache miss. Pointed at a folder that pinned nothing, the same command gave the hash that plain `rustc -Vv` gave there, and the next two runs restored the task from the cache.
1541
+
1542
+ So `RUSTUP_AUTO_INSTALL=0` turns rustup's download of a pinned toolchain into a failure whose message names the toolchain, and it changes nothing where cargo is no rustup proxy. Nx 24.0.6 does not fail a task whose runtime input fails: it keys the task on the command's output and runs the task. Keyed on rustup's message, the task would name the toolchain only as the toolchain file does, for a channel such as `stable` not the release that cargo would install. A random value printed in its place, with rustup's message discarded, gives each evaluation a key of its own and leaves the key of an installed toolchain as it was.
1543
+ :::
1544
+
1545
+ :::mara evidence EVD-NX-24-SETUP
1546
+ :mid: 01M7A67N99XVQ7ZV6NVRJB0W8N
1547
+ :title: How Nx 24.0.6 adds a plugin, runs generators and shows plugin output
1548
+ :status: accepted
1549
+ :supports: DES-GENERATORS
1550
+ :supports: DES-DIAGNOSTICS
1551
+
1552
+ Inspection of the `nx`, `@nx/devkit` and `@nx/js` 24.0.6 packages installed in this repository, and experiments with that `nx` package, on 13 November 2026. Paths are relative to `nx/dist/src/` unless another package is named.
1553
+
1554
+ Read in the compiled source:
1555
+
1556
+ - **`nx add`.** For a package outside Nx's own package group, `nx add <package>` installs `latest` unless a version is given, then runs `nx g <package>:init` with the terminal attached, adding `--keepExistingVersions` or `--updatePackageScripts` only when the init schema declares them. When `init` fails, the command exits with status 1 and the package stays installed (`command-line/add/add.js`, `command-line/init/configure-plugins.js`).
1557
+ - **The graph comes first.** `nx g` creates the project graph, with every registered plugin, before it runs any generator, unless `--skipProjectGraph` is given (`command-line/generate/generate.js`).
1558
+ - **Dry run.** Nx lists a generator's changes to its file tree after the generator returns, and writes them and runs the callback the generator returns only without `--dry-run` (`generate.js`). It takes `dryRun` out of the options it hands the generator and sets `NX_DRY_RUN` to `true` or `false` for the run (`generate.js`, `command-line/generate/command-object.js`).
1559
+ - **Prompts.** Prompts for options appear only when standard output is a terminal and `CI` is not `true` (`utils/params.js`).
1560
+ - **Directory.** The devkit helper for project names and roots resolves a generator's `directory` against the folder `nx` runs in, unless the path already starts with that folder (`@nx/devkit`, `generators/project-name-and-root-utils.js`). `@nx/js:library` requires `directory`, takes it from the first positional argument, and has an optional `name` (`@nx/js`, `generators/library/schema.json`).
1561
+ - **Plugin output.** Plugin workers run with their standard output and error piped into the process that started them (`project-graph/plugins/isolation/isolated-plugin.js`), and the daemon's standard output and error go to its log file (`daemon/client/client.js`). The plugin interface has no channel for warnings (`project-graph/plugins/public-api.d.ts`).
1562
+ - **Environment.** A client's first message carries its environment to the daemon, which applies it, forwards it to the plugin workers and recomputes a graph that was created under other values (`daemon/client/client.js`, `daemon/server/handle-client-env.js`).
1563
+ - **Ignored paths.** Besides what `.gitignore` and `.nxignore` exclude, and on the machine where it runs what git's exclude files outside the repository exclude (observed below), Nx always ignores only `**/node_modules`, `**/.git`, `**/.nx/cache`, `**/.nx/workspace-data` and `**/.yarn/cache`, as printed by calling `getHardcodedIgnorePatterns()` from `nx/src/native`.
1564
+ - **Codes.** A search of `nx/dist/src` found no numbered codes for user-facing diagnostics, such as `NX` followed by digits.
1565
+ - **TOML.** `nx` depends on `smol-toml`; `@nx/devkit` has no TOML dependency.
1566
+
1567
+ Observed in a throwaway git repository outside this one, with that `nx` package linked into its `node_modules`, Node.js 26.12.0, one `Cargo.toml` and a local plugin file listed in `nx.json` whose `createNodes` printed a line with `console.warn`, including the value of an environment variable:
1568
+
1569
+ - With `NX_DAEMON=false`, `nx show projects` printed the line in the terminal.
1570
+ - With `NX_DAEMON=true`, the terminal showed only the project list, and the line appeared in `.nx/workspace-data/d/daemon.log`. A second run with the same environment did not run the plugin again. A run with the variable changed made the daemon log "Graph recompute necessary due to env variable refresh. Changed keys: …", and the plugin printed the new value there.
1571
+ - A second local plugin whose module threw when loaded made `nx run js-app:build`, the `package.json` script of a JS project, fail with "Failed to load 1 Nx plugin(s)" and the thrown message, exit status 1. `nx show projects` and `nx g <package>:init` failed the same way. `nx --version` still worked, and so did `nx g <package>:init --skipProjectGraph`, which ran the generator.
1572
+ - A `crate/target` folder that neither `.gitignore` nor `.nxignore` covered was part of the crate's project: Nx's file map listed `crate/target/junk.rs` among the project's files, and the plugin was handed a `Cargo.toml` from `crate/target/package/`. With `target/` in `.nxignore` alone, neither happened. Neither did it for `crate/.nx/cache/target` and `crate/node_modules/target`, which `git check-ignore` confirmed neither ignore file covered, with `.gitignore` holding only `/.nx` and no `.nxignore`: Nx's fixed exclusions kept the files of both out of the file map, and the plugin was not handed the `Cargo.toml` under `crate/.nx/cache/target/package/`.
1573
+
1574
+ Observed with pnpm 12.18.0 in a second throwaway repository, whose `package.json` linked that `nx` package, and a local package whose `init` generator threw: `nx add probe-plugin@file:<folder>` added the package to `package.json` and `pnpm-lock.yaml` and installed it, then failed with the generator's message and exit status 1. The package stayed in `package.json` and `node_modules`, and `nx.json` was unchanged.
1575
+
1576
+ Observed on 14 November 2026 in a third throwaway repository, with that `nx` package linked into its `node_modules`, Node.js 26.12.0, git 2.56.0 and `NX_DAEMON=false`. Git's configuration was kept from the user's: `GIT_CONFIG_GLOBAL` named an empty file, `GIT_CONFIG_NOSYSTEM` was `1`, `XDG_CONFIG_HOME` named a folder of the experiment's own, and the home folder held no `.gitconfig`. The repository held `a/target/junk.rs`, `b/target/junk.rs` and `c/target/junk.rs`, and no `.gitignore` or `.nxignore`. `globWithWorkspaceContext(root, ["**/target/**"])` from `nx/src/utils/workspace-context` listed the files that Nx reads, and `isIgnoredDirectory` of `createGitIgnoreChecker` from `nx/src/devkit-internals` gave what Nx's reading of the ignore files on disk leaves out:
1577
+
1578
+ - In a git repository whose `.git/info/exclude` named `/a/target/` and whose global excludes file, `$XDG_CONFIG_HOME/git/ignore`, named `b/target/`, as `git check-ignore -v` confirmed, Nx listed only `c/target/junk.rs`, while `isIgnoredDirectory` returned `false` for all three folders.
1579
+ - With `.git` removed, Nx listed `a/target/junk.rs` and `c/target/junk.rs`: the global excludes file still kept `b/target` out, and so it did in a copy of the repository that never had `.git`. With `XDG_CONFIG_HOME` naming an empty folder instead, Nx listed all three files.
1580
+ - With `core.excludesFile` in `$XDG_CONFIG_HOME/git/config` naming a file that listed `c/target/`, Nx left out `c/target` and no longer `b/target`, so it reads the excludes file that git's configuration names in place of the default one.
1581
+ :::
1582
+
1583
+ :::mara evidence EVD-NX-24-VERSION-CHECK
1584
+ :mid: 01M7AR5NQ71CB4YNT6NRTYWHJZ
1585
+ :title: How Nx 24.0.6 and pnpm 12.18.0 treat a plugin that checks the Nx version
1586
+ :status: accepted
1587
+ :supports: DES-DIAGNOSTICS
1588
+ :supports: DES-GENERATORS
1589
+
1590
+ Inspection of the `nx` 24.0.6 package installed in this repository, and experiments with it and with pnpm 12.18.0, on 13 November 2026, while implementing the version checks of [[DES-DIAGNOSTICS]]. Paths are relative to `nx/dist/src/`.
1591
+
1592
+ Read in the compiled source:
1593
+
1594
+ - **The installed Nx.** Nx takes the version of the installed Nx from the `nx/package.json` that resolves from `.nx/installation` and then from the repository root (`utils/installed-nx-version.js`, `utils/installation-directory.js`), and finds the repository root from the folder it runs in, or from `NX_WORKSPACE_ROOT_PATH` (`utils/workspace-root.js`). When that version differs from the version of the Nx that runs, the client does not use the daemon (`daemon/client/client.js`, `daemon/is-nx-version-mismatch.js`).
1595
+ - **Hooks without files.** Graph creation calls each plugin entry's `createNodes`, also when none of the repository's files matches the entry's pattern, `include` and `exclude`: it then hands the entry an empty list (`project-graph/utils/project-configuration-utils.js`).
1596
+ - **Reloads.** A plugin in a worker, the default, whose last hook is `createDependencies` has its worker shut down after that hook, and the next hook call starts a new worker that loads the module again (`project-graph/plugins/isolation/isolated-plugin.js`, `plugin-lifecycle-manager.js`). A plugin loaded into Nx's own process, with `NX_ISOLATE_PLUGINS=false`, stays loaded. When a client's environment changes, the daemon forwards it to the workers and discards its graph, but it loads no plugin again (`daemon/server/handle-client-env.js`). A failed load is not kept: the next graph creation loads the plugin again (`project-graph/plugins/get-plugins.js`, `isolation/load-isolated-plugin.js`).
1597
+ - **Errors of `createDependencies`.** When `createNodes` fails, graph creation still calls `createDependencies` with the projects it has, and then reports the errors of both, an error of `createDependencies` as `The "<plugin>" plugin threw an error while creating dependencies: <message>` (`project-graph/project-graph.js`, `project-graph/build-project-graph.js`, `project-graph/error-types.js`). Graph creation merges the projects of the plugins of `nx.json` with those of Nx's default plugins for `package.json` and `project.json` before it calls `createDependencies` with them by name.
1598
+ - **Internals.** The `exports` of `nx/package.json` include `./src/*`, so `nx/src/project-graph/plugins/get-plugins` and `nx/src/project-graph/utils/retrieve-workspace-files`, which load the plugins of `nx.json` and read the files of the repository by project, can be required alongside `nx/src/devkit-internals`.
1599
+
1600
+ Observed in a throwaway git repository outside this one, with one `Cargo.toml` and a local plugin file in `nx.json` that printed a line when it loaded and when its hooks ran, and could throw from either, run with a copy of that `nx` package whose `package.json` gave the version 25.0.0, linked as the repository's `node_modules/nx`:
1601
+
1602
+ - `nx --version` reported the local Nx as 25.0.0, and the copy created the graph, with the plugin in a worker and in Nx's own process.
1603
+ - A throw when the module loaded made `nx show projects` fail with "Failed to load 1 Nx plugin(s)" and the message.
1604
+ - With `NX_DAEMON=true`, the daemon log showed Nx 25.0.0. Changing a variable between runs made the daemon log "Graph recompute necessary due to env variable refresh", restart the plugin's worker and load the module again with the new value. A throw from `createNodes` failed the run, the next run with another value succeeded, and the run after that with the first value failed again. A throw when the restarted worker loaded the module failed both hooks, so the message appeared twice, once for `createNodes` and once for `createDependencies`.
1605
+
1606
+ Observed with pnpm 12.18.0 in a second throwaway repository that installed `nx` 24.0.6 from pnpm's store: adding a local package whose peer dependency range on `nx` was `^23` printed "Issues with peer dependencies found" and exited with status 0, with the package installed. `pnpm peers check` then listed the unmet peer with the installed and wanted versions and exited with status 1. pnpm linked the repository's `nx` into the package's folder in its store, so that `nx` resolves from the package. With the range `^24`, neither printed anything about peers.
1607
+
1608
+ So a plugin that checks the version only when its module loads misses a change of `NX_RUST_ALLOW_UNSUPPORTED_NX` while a daemon runs it in Nx's own process, and a check in `createNodes` runs on every graph computation, also in a repository without a `Cargo.toml`. The peer dependency range does not stop an install with another Nx major; only the plugin's own check stops it.
1609
+ :::
1610
+
1611
+ :::mara evidence EVD-NX-24-WARNING-CHANNELS
1612
+ :mid: 01M7CN8CQT805NSVGPERYK9BAK
1613
+ :title: Where Nx 24.0.6 shows what a plugin prints, and how a project's warnings can reach its keys
1614
+ :status: accepted
1615
+ :supports: DES-DIAGNOSTICS
1616
+ :supports: DES-INPUTS
1617
+ :supports: DES-TARGET-DEFAULT-GUARD
1618
+
1619
+ An investigation on 14 November 2026 with the `nx` 24.0.6 package that this repository installs, Node.js 26.12.0 and cargo 1.100.0 on Linux, in a copy of the `patched-workspaces` fixture outside this repository. `nx.json` listed the compiled plugin and, after it, a probe plugin that recorded where each of its hooks ran and printed through each channel a plugin has. The `model` line of the root manifest's `[patch]` was removed, as the redirection tests remove it. Commands ran without the variables from which Nx concludes that an agent runs it, with `CI` set only where stated, with one private `NX_CACHE_DIRECTORY`, a private Cargo home, `CARGO_NET_OFFLINE=true` and `RUSTUP_AUTO_INSTALL=0`; the terminal UI ran in a pseudo-terminal of 120×40. Paths are relative to `nx/dist/src/`. The same day, the rows marked "Rerun" were repeated through this repository's test harness, in its fixed environment, with a probe plugin that printed from `createNodes`, `preTasksExecution` and `postTasksExecution` and gave `util` a named input or a metadata value taken from an environment variable; keys were computed with Nx's own task hasher.
1620
+
1621
+ - **The hooks around a command's tasks.** `preTasksExecution` and `postTasksExecution` run for `nx run`, `nx run-many` and `nx affected`, also when no task runs, and not for `nx show`, `nx graph` or `nx exec`. Without the daemon they run in a plugin worker whose standard streams are piped to `nx` (`project-graph/plugins/isolation/isolated-plugin.js`), or in `nx` itself with `NX_ISOLATE_PLUGINS=false`, and what they print reached the terminal in every output style, also with `CI=true`. With the daemon they run in a worker that the daemon started, or in the daemon itself without isolation, and what they print goes to the daemon's log; a line sent with `emitPluginWorkerLog` is dropped there, because no client listens (`daemon/server/client-socket-context.js`). The pre hook receives the workspace root, `nx.json` and the command's arguments, but no project graph or task graph; the post hook adds each task's result, which says whether the cache restored it. Rerun: `nx run plain:fmt-check` and `nx run-many -t fmt-check --projects=plain,api`, each with `--output-style=static` and `stream`, printed the lines of both hooks without the daemon, with plugin workers and in Nx's own process, and printed neither with `NX_DAEMON=true`, where the daemon's log held them.
1622
+ - **Graph creation.** Rerun: what `createNodes` printed with `console.warn` reached the terminal without the daemon and only the daemon's log with it, as [[EVD-NX-24-SETUP]] found. A line that a plugin worker sends to the daemon's clients reaches only a command that waits for that graph computation: it was printed when the daemon started and when `nx` ran right after an edit, and not when the command started 8 seconds after the edit, by which time the daemon had created the graph in the background (`daemon/server/project-graph-incremental-recomputation.js`).
1623
+ - **How fresh the graph is.** Without the daemon, every command created the graph again. The daemon creates it again when its file watcher reports a change in the repository, when a client's environment changes and when it starts, never for a change outside the repository. After a `[patch]` was added to the Cargo home's `config.toml`, a cache hit printed no warning, and the graph had none, until a file in the repository changed. After the `[patch]` was removed, the graph kept the warning until a file in the repository changed again.
1624
+ - **What a hit replays.** Nx stores only what a task's own process writes, and replays it on a cache hit. Of 19 stored outputs, none held a line of a hook, and the two that held the warning had it from the plugin's executor. Without the daemon, after the `[patch]` was removed, a hit replayed the warning that neither the graph nor the hooks had any more. The terminal UI's summary of several tasks shows only failed or stopped tasks, and its summary of a single task shows it whole (`tasks-runner/life-cycles/tui-summary-life-cycle.js`); with `CI=true`, Nx left out the output of a dependency that succeeded.
1625
+ - **What reaches a key.** Rerun: the probe gave the project `util` a named input that no target names, holding `{ "runtime": "echo <value>" }`. Changing the value from `a` to `b` changed the keys of `util:fmt-check` and `util:check`, and of `model:check`, whose crate depends on `util`. It changed none of the keys of `api:check`, `plain:fmt-check`, `plain:check` and `types:check`. Giving `util` the value as project metadata instead changed none of these seven keys. In Nx's native hasher, `hash_project_config` sorts a project's named inputs by name and hashes their entries, as the hasher's symbols show; [[EVD-NX-OPTION-VALIDATION]] lists the named inputs among the parts of the project's configuration that every key holds.
1626
+ - **The lockfile task's output, and `--skip-nx-cache`.** Observed on 14 November 2026 through this repository's test harness with the daemon on, in a copy of `patched-workspaces` whose ignored `rust/.cargo/config.toml` set `[env]`, so that the lockfile task of `rust` printed the warning about that file. For `nx run plain:build`, the default output style without a terminal, with `CI` false and true, showed "✔ nx run rust:lockfile" and "Output of 1 successful task was not shown. Run with --verbose or --output-style=static to see it."; so did a pseudo-terminal with `CI=true`. In a pseudo-terminal without `CI`, Nx showed "1/1 dependent project tasks succeeded" and "Hint: you can run the command with --verbose to see the full dependent project outputs". The warning appeared in none of these outputs. Once `plain:build` printed the warning itself, it appeared under that task's header in each of these modes, when the task ran and when the cache restored it. A run with `--skip-nx-cache` stored nothing: a run without the flag after it restored the result stored before it, and after `nx reset` the task ran. In the source, the task orchestrator passes `doNotSkipCache`, false with `--skip-nx-cache`, as the `shouldCache` argument of `postRunSteps`, which writes to the cache only where it is true (`tasks-runner/task-orchestrator.js`).
1627
+ - **Other channels.** A custom hasher runs in `nx` for every task, cache hits included, but Nx marks it for removal in Nx 25 (`hasher/hash-task.js`), and it runs after the terminal UI has started, which drops what `nx` prints. The task runner's life cycles are fixed, unless a custom tasks runner in `nx.json` replaces Nx's own. `createMetadata` runs during graph creation, in the same process as the other graph hooks.
1628
+ - **`createMetadata`.** Read in the source: Nx calls a plugin's `createMetadata` after `createDependencies`, with the project graph as Nx merged it, as a method of its copy of the plugin for the entry (`project-graph/plugins/loaded-nx-plugin.js`), in the same worker, whose graph phase is `createNodes`, `createDependencies` and `createMetadata` (`project-graph/plugins/isolation/plugin-lifecycle-manager.js`). It merges the metadata returned for each project into the project's own: an object under a key key by key, a list onto a list (`applyProjectMetadata` in `project-graph/build-project-graph.js`, `mergeMetadata` in `project-graph/utils/project-configuration/target-merging.js`). Observed the same day through the plugin's tests: warnings that `createMetadata` put under `cargo.targetWarnings` reached the executor's context, with the daemon on and off, and each task of the target concerned printed them.
1629
+ - **A file that `nx.json` extends.** Observed the same day with Nx's own hasher: with `nx.json` extending `./base.json` in `patched-workspaces`, giving `base.json` an entry of `targetDefaults` left the hash of the file input `{workspaceRoot}/nx.json, .gitignore, .nxignore` of `api:fmt-check` and `plain:fmt-check` as it was. Only the projects' configuration changed, through the plugin's digest. Nx hashes `nx.json` itself into every key ([[EVD-NX-OPTION-VALIDATION]]), but not the file that it extends.
1630
+
1631
+ So with the daemon, nothing that a plugin prints outside a task reaches the terminal of a command; only a task's own output does, and a hit replays it as stored. A hit therefore shows the warnings of the graph that the command uses only where the warnings are part of the task's key, which a named input of the project can make them without any target naming it. macOS, Nx Console and the batch implementation's replay were not tried.
1632
+ :::
1633
+
1634
+ :::mara evidence EVD-CARGO-TARGET-COMMANDS
1635
+ :mid: 01M7A4FCEFVN0W56WPDHWWW88N
1636
+ :title: What cargo, rustfmt and rust-analyzer 1.100 do with the commands of the inferred targets
1637
+ :status: accepted
1638
+ :supports: DES-TARGET-COMMANDS
1639
+ :supports: DES-WORKSPACE-TARGETS
1640
+ :supports: ADR-NX-TARGET-NAMES
1641
+ :supports: DES-INPUTS
1642
+ :supports: DES-INVOCATION
1643
+ :supports: DES-BATCH
1644
+
1645
+ Experiments on 13 November 2026 with cargo 1.100.0 (3acc79c0c 2026-11-05), rustc 1.100.0, clippy 0.1.100, rustfmt 1.11.0 and rust-analyzer 1.100.0, all from one rustup toolchain, in a throwaway virtual workspace outside this repository. Its members were `a`, a library with a `harness = false` bench and a deliberate unused variable, and `b`, a crate with two binaries, `b` and `second`, that depends on `a`. `a` also depended on `ext`, a path dependency outside the workspace. For one check cargo 1.89.0, 1.91.0, 1.96.0, 1.97.0, 1.97.1 and 1.98.1 were used as well, each with a target directory of its own; 1.91.0, 1.96.0 and 1.97.0 were installed with the minimal profile into a rustup home of their own.
1646
+
1647
+ - **check and clippy.** `cargo check --all-targets -p a` checked `ext` and `a`. A following `cargo clippy --all-targets -p a` checked `a` again and reused `ext`. Alternating `cargo clippy --all-targets -p a` with `cargo clippy --all-targets -p a -- -D warnings` checked `a` again on every switch, and the run with `-D warnings` failed on the warning.
1648
+ - **build.warnings.** `CARGO_BUILD_WARNINGS=deny cargo clippy --all-targets -p a` failed with "warnings are denied by `build.warnings` configuration", and a plain `cargo clippy --all-targets -p a` afterwards checked nothing again. `CARGO_BUILD_WARNINGS=deny cargo check -p a` failed in the same way with cargo 1.97.0, 1.97.1, 1.98.1 and 1.100.0, and with cargo 1.89.0, 1.91.0 and 1.96.0 it succeeded with the warning and no notice about the setting. Cargo's configuration reference (doc.rust-lang.org/cargo/reference/config.html, read the same day) gives the same boundary for `build.warnings`: "MSRV: Respected as of 1.97". With cargo 1.100.0 and `CARGO_BUILD_WARNINGS=deny`, `cargo run -p b --bin second` and `cargo bench -p a` failed the same way on the warning in `a`, since both compile it.
1649
+ - **build.warnings in the test steps** (22 November 2026, nxr-w1qhmx; cargo 1.100.0, 1.97.1 and 1.91.0 from the same rustup installation). In a copy of the `workspace-tests` fixture with an unused variable in the library of `d`, `CARGO_BUILD_WARNINGS=deny cargo test --workspace --no-run` exited with 101 and printed, after the warning, ``error: `d` (lib) generated 1 warning (run `cargo fix --lib -p d` to apply 1 suggestion)``, then ``error: warnings are denied by `build.warnings` configuration`` and `warning: build failed, waiting for other jobs to finish...`. Each unit with warnings got such a pair of lines, its package's name in backquotes, as ``error: `d` (lib test) generated 1 warning (1 duplicate)``; without denied warnings the same summaries start with `warning:`. With warnings in `a` and `d`, a run that compiled `a` first named only `a`, having started no new job after it. Runs on fresh units replayed the warnings and the lines. `CARGO_TERM_COLOR=always` coloured the word `error` alone. `--message-format json-render-diagnostics`, as nextest builds, printed the same lines on standard error and `{"reason":"build-finished","success":false}`. `build.warnings = "deny"` in the workspace's `.cargo/config.toml` failed `cargo test -p a -p b` with the same lines. Cargo 1.97.1 printed the same; with cargo 1.91.0 the summaries started with `warning:`, no line said that warnings were denied, and the command exited with 0. A review of the pull request the same day, with cargo 1.100.0, found that with `CARGO_TERM_PROGRESS_WHEN=always` and `CARGO_TERM_PROGRESS_WIDTH=80` cargo wrote its progress bar and a carriage return before the next line on the same line, before a `warning:` and before an `error:` summary alike, also where its output was captured; that `cargo test -p a -p b --no-fail-fast`, with a build script of `b` that failed and a denied warning in `a`, printed ``error: failed to run custom build command for `b v0.1.0 (…)` `` and the summaries and denial lines of `a`; that the denial lines also appeared in `cargo test --workspace --doc`, though no run tried reached that step without the build step stopping first; and that a warning in a file that one member compiles from another member's folder with `#[path]` was located in that folder while cargo's summary named the member that compiled it. A build script's `cargo::warning` and a warning in a doctest's code did not fail any command on their own.
1650
+ - **build.warnings under JSON messages** (22 November 2026, nxr-tjxcvx; cargo 1.100.0, 1.97.1 and 1.91.0 from the same rustup installation). A second virtual workspace had the members `a` and `b`, `b` depending on `a`, each library with an unused variable. With `CARGO_BUILD_WARNINGS=deny` and cargo 1.100.0, `cargo check --workspace --keep-going --message-format=json` exited with 0, with `{"reason":"build-finished","success":true}` and one `compiler-message` of level `warning` for each of `a` and `b`, naming its package; nothing in the messages or on standard error said that warnings were denied, and no other `compiler-message` was printed, so no summary such as "1 warning emitted" either. `cargo clippy` with the same flags exited with 0 too. The same command without `--message-format` exited with 101 and "warnings are denied by `build.warnings` configuration", after checking both crates: a warning stops no job. `--message-format=json-render-diagnostics` exited with 101 as well, but printed the diagnostics rendered on standard error and no `compiler-message`, so that nothing tied a warning to its package but cargo's human-readable summary lines. `--message-format=json,json-diagnostic-short` and `json,json-diagnostic-rendered-ansi` exited with 0. Runs on fresh units replayed the warnings, in the messages and in the plain output, and the plain run failed again without compiling anything. `build.warnings = "deny"` in the workspace's `.cargo/config.toml` behaved as the variable did: 101 without `--message-format`, 0 with JSON messages, also with cargo 1.97.1; with cargo 1.91.0 both exited with 0. `CARGO_BUILD_WARNINGS=warn` over that file exited with 0, and `--config 'build.warnings="deny"'` over `CARGO_BUILD_WARNINGS=warn` with 101, the precedence of Cargo's configuration reference. `CARGO_BUILD_WARNINGS=allow` hid the warnings of the plain run and exited with 0, while the JSON messages still reported both warnings. `CARGO_BUILD_WARNINGS=bogus` failed every command, JSON messages included, with "unknown variant `bogus`, expected one of `warn`, `allow`, `deny`". With `b` clean, `CARGO_BUILD_WARNINGS=deny cargo check -p b` failed on the warning in `a`, and, with `a` clean too, on one in `ext`, a path dependency of `b` outside the workspace, whose warning the JSON messages reported under `ext`'s package ID. A review of the pull request of nxr-tjxcvx the same day, with cargo 1.100.0 in the `workspace-tests` fixture, where the member `b` turns on the feature `x` of the member `shared` and `a` does not, found that with a warning behind `#[cfg(not(feature = "x"))]` in `shared` and `CARGO_BUILD_WARNINGS=deny`, `cargo check --offline --all-targets -p a` exited with 101, while the command that selects the whole workspace with JSON messages compiled `shared` with `x` and reported no warning for it.
1651
+ - **rust-analyzer.** `rust-analyzer --print-config-schema` gives `cargo.allTargets` the default `true`, `check.allTargets` the default of `cargo.allTargets`, `check.workspace` the default `true` and `check.command` the default `"check"`. The editor's check is therefore `cargo check --workspace --all-targets`.
1652
+ - **Nightly benches.** With a bench in `b` that uses `#![feature(test)]`, `cargo check --all-targets -p b` failed on stable with E0554, while `cargo check -p b` passed. So did `cargo check -p a -p b`, while `cargo check --all-targets -p a -p b` failed with E0554: one call cannot check `a` with `--all-targets` and `b` without.
1653
+ - **fmt.** `cargo fmt --check --all` reported files of `ext` as well as of the members, and `cargo fmt --all` rewrote `ext`'s source. `cargo fmt --check` without flags, run in the workspace root, reported exactly the members' files, both in this virtual workspace and in a second one whose root manifest is a package with one more member. `cargo fmt --check -p a -p b` checked both crates. A package ID spec after `-p` was rejected as "not a member of the workspace", while `--manifest-path crates/a/Cargo.toml` selected `a`. `cargo fmt --check` exited with 1 when a file needed formatting. `cargo fmt --locked -p a`, `cargo fmt --check --locked -p a` and `cargo fmt -p a --locked` failed with exit code 2 and "unexpected argument '--locked' found"; `cargo fmt --help` lists no `--locked`, `--offline` or `--frozen`.
1654
+ - **doc.** `cargo doc --no-deps -p a` and then `cargo doc --no-deps -p b` wrote `doc/a`, `doc/b` and `doc/second`, one folder per documented library or binary, and `doc/src/a`, `doc/src/b` and `doc/src/second`, beside files that both runs shared: `crates.js`, `search.index`, `src-files.js`, `static.files`, `help.html` and `settings.html`. `crates.js` listed `a` after the first run and `a`, `b` and `second` after the second. `doc/a/index.html` loads its styles from `../static.files/`. `cargo doc --no-deps --workspace` documented both members in one run.
1655
+ - **run.** `cargo run -p b` failed with "`cargo run` could not determine which binary to run" and listed `b, second`; `cargo run -p b --bin second -- x` ran `second`. `cargo run -p a -p b` failed because `--package` cannot be given more than once.
1656
+ - **bench.** `cargo bench -p a` ran on stable: the library's test harness in bench mode and then the `harness = false` bench.
1657
+ - **update.** After a new path dependency was added to a manifest, `cargo update --locked` failed with "cannot update the lock file … because --locked was passed to prevent this", and `cargo update` then updated `Cargo.lock`. Without such a change, `cargo update --locked` succeeded.
1658
+
1659
+ The workspace was a toy, so nothing here says how long these commands take on a large one.
1660
+ :::
1661
+
1662
+ :::mara evidence EVD-CARGO-AUDIT-DENY
1663
+ :mid: 01M7A4FCEFMBYHR6YR0ZANHNS3
1664
+ :title: What cargo-audit 0.23.0 and cargo-deny 0.20.2 read, fetch and write
1665
+ :status: accepted
1666
+ :supports: DES-WORKSPACE-TARGETS
1667
+ :supports: DES-INVOCATION
1668
+
1669
+ Experiments on 13 November 2026 with cargo-deny 0.20.2 and cargo-audit 0.23.0, installed with `cargo install --locked` into a throwaway folder, and cargo 1.100.0, with a Cargo home of their own that started empty. The workspace, outside this repository, had one member `x` with `license = "MIT"` that depended on the registry crate `itoa`, whose license is `MIT OR Apache-2.0`. Every command ran in the workspace root.
1670
+
1671
+ - **No configuration.** Without a configuration file, `cargo deny check` warned "unable to find a config path, falling back to default config", rejected the licenses of `itoa` and `x`, and exited with code 4; advisories, bans and sources passed. A configuration that allows MIT and Apache-2.0 made the license check pass when it was `deny.toml`, `.deny.toml` or `.cargo/deny.toml` in the workspace root. `cargo deny --help` says the configuration defaults to `deny.toml` in the current folder.
1672
+ - **Network.** Both tools fetched the RustSec advisory database into the Cargo home: cargo-audit printed "Fetching advisory database from `https://github.com/RustSec/advisory-db.git`" and loaded 1490 advisories. cargo-audit also updated the crates.io index.
1673
+ - **Lockfile.** After a dependency was added to the member's manifest, `cargo deny check` updated `Cargo.lock`. `cargo deny --locked check` failed instead with Cargo's "cannot update the lock file … because --locked was passed to prevent this" and left the file unchanged. `cargo audit` scanned the old `Cargo.lock`, which did not list the new dependency, and left it unchanged. Its options include `--no-fetch` and `--stale`, and none like `--locked`.
1674
+ - **cargo-audit configuration.** An invalid `.cargo/audit.toml` in the workspace root made `cargo audit --no-fetch` fail with a TOML parse error. The same file as `audit.toml` in the workspace root, or as `.cargo/audit.toml` in the member's folder, was ignored.
1675
+
1676
+ What these tools report thus depends on the advisory database at the time they run, not only on files in the repository.
1677
+ :::
1678
+
1679
+ :::mara evidence EVD-NX-24-TARGETS
1680
+ :mid: 01M7A4FCEFW4N06285629BJCB1
1681
+ :title: What Nx 24.0.6 does with continuous, sequential and overlapping targets
1682
+ :status: accepted
1683
+ :supports: DES-TARGET-COMMANDS
1684
+ :supports: DES-WORKSPACE-TARGETS
1685
+ :supports: DES-OUTPUTS
1686
+ :supports: ADR-NX-TARGET-NAMES
1687
+
1688
+ An experiment and a reading of the `nx`, `@nx/js` and `@nx/workspace` 24.0.6 packages installed in this repository, on 13 November 2026, with Node.js 26.12.0. The experiment used a throwaway workspace outside this repository with two projects, `a` and `b`, whose targets ran shell commands through `nx:run-commands`. Nx ran as `node <repository>/node_modules/nx/dist/bin/nx.js` with `NX_DAEMON=false`, `NX_NO_CLOUD=true` and `NX_TUI=false`.
1689
+
1690
+ - **Overlapping outputs.** Each project's cached `doc` target wrote a folder of its own under `out/doc` and a shared `out/doc/crates.js`, and declared `{workspaceRoot}/out/doc` as its output. After `nx run a:doc` and `nx run b:doc`, `out/doc` held both folders. A second `nx run a:doc` was a cache hit, after which `out/doc` held only `a`'s folder and `a`'s `crates.js`: the restore replaced the whole folder. The native cache documents `copyFilesFromCache` as replacing each output that exists (`native/index.d.ts`).
1691
+ - **Continuous tasks that exit.** A target with `continuous: true` printed a line and exited. Run alone with `nx run a:oneshot`, it succeeded. As the dependency of another target, `nx run a:after` failed with `Task "a:oneshot" is continuous but exited with code 0` and exit code 1 (`tasks-runner/task-orchestrator.js`).
1692
+ - **A project without a target.** `nx run a` failed with "Both project and target have to be specified".
1693
+ - **Batches.** Without `--batch`, a task joins a batch only if its executor has a batch implementation and sets `preferBatch`, and only if the task's `parallelism` is not `false`. A continuous task stays out of a batch only when another task depends on it or it declares `readyWhen` (`processTaskForBatches` and `canBatchTaskBeScheduled` in `tasks-runner/tasks-schedule.js`).
1694
+ - **Parallelism.** While a task with `parallelism: false` runs, no other task starts, and such a task starts only when no other task runs (`canBeScheduled` in `tasks-runner/tasks-schedule.js`).
1695
+ - **Readiness.** A target accepts `continuous`, `readyWhen` and `parallelism` (`schemas/project-schema.json`). `readyWhen` waits for a `url`, a `port`, a `command` or `logMatches`, and a dependent waits for it only with `waitFor: "ready"` on its `dependsOn` entry; the default is `started`.
1696
+ - **nx watch.** `nx watch` runs its command once for each batch of changes and takes the next batch only after the command has exited, so it cannot restart a command that keeps running (`command-line/watch/watch.js`).
1697
+ - **Command names.** `run` and `watch` are Nx commands, so `nx run <project>` never runs a target named `run`. `check`, `doc`, `bench`, `fmt`, `fmt-check`, `audit`, `deny`, `update` and `typecheck` are not command names (the command handlers of `command-line/nx-commands.js` and `isKnownCommand` in `bin/init-local.js`).
1698
+ - **typecheck.** `@nx/js` adds its TypeScript plugin with the target name `typecheck` (`src/utils/typescript/add-typescript-plugin.js`), and the CI workflow generator of `@nx/workspace` writes `nx affected -t lint test build typecheck` when a workspace has that target (`src/generators/ci-workflow/ci-workflow.js`).
1699
+
1700
+ The targets of the experiment ran no cargo. The points marked with a source file were read, not run.
1701
+ :::
1702
+
1703
+ :::mara evidence EVD-NX-24-EXTERNAL-NODES
1704
+ :mid: 01M7ACCPE3NW5Z2SMKCY08AV3H
1705
+ :title: What Nx 24.0.6 does with external nodes, externalDependencies and a lockfile it does not parse
1706
+ :status: accepted
1707
+ :supports: ADR-LOCKFILE-TASK
1708
+ :supports: DES-INPUTS
1709
+ :supports: DES-LOCKFILE-HASHING
1710
+
1711
+ Experiments on 13 November 2026 with `nx` 24.0.6, pnpm 12.18.0, Node 26.12.0 and git 2.56.0 on Linux x86-64. The throwaway workspace lay outside this repository, was installed with `pnpm install --offline` and had the default task-based affected. A local plugin made the projects `a`, `b` and `c` from `rust/crates/*/Cargo.toml` and read a hand-written `rust/Cargo.lock` in Cargo's version 4 format, in which `a` depended on `serde`, `serde` on `serde_derive`, `b` on `itoa` and `c` on `a`. It turned every package with a `source` into an external node `cargo:<name>@<version>` of type `cargo`, with the package's checksum as `data.hash`. Its `createDependencies` returned an edge from each crate to its direct external dependencies, an edge from each external node to those its lockfile entry lists, and the project edge from `c` to `a`. The targets used `nx:run-commands`, `nx:noop` and an executor from a package installed with `file:`; a JS project listed in `pnpm-workspace.yaml` added a `package.json` script. Hashes came from Nx's own hasher: a script built the graph with `createProjectGraphAsync` and the task graph with `createTaskGraph`, called `InProcessTaskHasher.hashTask` and printed each task's hash with its parts, all with `NX_DAEMON=false NX_CACHE_PROJECT_GRAPH=false`; `HashPlanInspector` printed the plans. Selection came from `nx affected -t <target> --base=HEAD~1 --head=HEAD --explain=stdout` after a commit.
1712
+
1713
+ - **Every external node by default.** A target without an `externalDependencies` input hashed `AllExternalDependencies`, every external node of the graph, npm and `cargo:` alike. That held for `nx:run-commands`, `nx:noop`, the executor from a package and the `package.json` script (`nx:run-script`), whose hash changed when only the hash of `cargo:itoa@1.0.0` changed. An `externalDependencies` input, an empty one included, removed it.
1714
+ - **Edges and `^` inputs.** With edges from projects to external nodes, a `^` input such as `^default` hashed the project's direct external nodes and, along the edges between external nodes, the nodes behind them: `serde` and `serde_derive` for `a`, and the same for `c` through its edge to `a`. A target without a `^` input hashed none of them.
1715
+ - **Named nodes.** `externalDependencies: ["cargo:serde@1.0.0"]` hashed that node and `serde_derive` behind it, and `["@exp/executor"]`, a bare package name, resolved to its `npm:` node. A name without a node failed hashing with "The externalDependency 'cargo:does-not-exist' for 'a:rc-extmissing' could not be found". A package name failed in the same way when `nx.json` set `pluginsConfig["@nx/js"].analyzeLockfile` to `false`, which leaves the graph without npm nodes.
1716
+ - **The `hash` field.** A changed checksum with the version unchanged changed the keys of exactly the tasks that reached the node. Without `data.hash`, a changed checksum changed no key, while a changed version, which renamed the node, did.
1717
+ - **One name twice.** When two `createNodes` results declared one node name with different hashes, the graph kept the last one, without a message.
1718
+ - **Affected.** After a commit that changed only `rust/Cargo.lock`, and with it the hash of `cargo:serde@1.0.0`, `nx affected` selected no task that reached that node, whether through a `^` input, `externalDependencies` or `AllExternalDependencies`. Only tasks with the lockfile as a file input were selected. Adding `Cargo.lock` to the plugin's `createNodes` pattern changed nothing. Neither did a per-crate digest that the plugin put into a target option, although the option changed the task's key through the project's configuration. As read in the installed source, Nx works out which external nodes moved only from the JS lockfiles and `package.json` (`dependencyChanges` in `project-graph/affected/affected-tasks.js`, `plugins/js/project-graph/affected/lock-file-changes.js`), and the plugin interface has no hook through which a plugin could report moved nodes (`project-graph/plugins/public-api.d.ts`).
1719
+ - **A JS lockfile.** After a commit that changed one integrity entry of `pnpm-lock.yaml`, with Nx's default `projectsAffectedByDependencyUpdates`, `nx affected` selected every crate target without an `externalDependencies` input, with the reason `external-dependencies`, and none of those with an empty one. A target that names an npm package fares otherwise, and the setting decides how ([[EVD-NX-24-PLUGIN-VERSION]]).
1720
+ - **Graph creation.** With the project graph cache on and the daemon off, a change to `Cargo.lock` alone made the next command create the graph again, and the node's hash followed the file.
1721
+
1722
+ The daemon was off throughout, the lockfile was written by hand and no cargo ran.
1723
+ :::
1724
+
1725
+ :::mara evidence EVD-NX-24-PLUGIN-VERSION
1726
+ :mid: 01M7AEAST02RW3QQS2PRMN6R21
1727
+ :title: How Nx 24.0.6 hashes a plugin's package, its dependencies and a project's configuration
1728
+ :status: accepted
1729
+ :supports: DES-INPUTS
1730
+ :supports: DES-PLUGIN-OPTIONS
1731
+ :supports: DES-LOCKFILE-HASHING
1732
+
1733
+ Experiments on 13 November 2026 with `nx` 24.0.6, pnpm 12.18.0, Node 26.12.0 and git 2.56.0 on Linux x86-64, in a throwaway workspace outside this repository installed with `pnpm install --offline`. An executor package `@exp/executor`, installed with `file:`, depended on `tslib` 2.9.1. A stand-in plugin, listed in `nx.json` by its path and not installed as a package, gave two crate projects `a` and `b` the targets `t` and `u` with that executor, their own files as input, and an `externalDependencies` input naming the plugin's package, the executor's package or nothing, as each case required. Hashes came from `InProcessTaskHasher.hashTask` as in [[EVD-NX-24-EXTERNAL-NODES]], with `NX_DAEMON=false NX_CACHE_PROJECT_GRAPH=false`, and the selection from `nx affected -t t --base=HEAD~1 --head=HEAD --explain=stdout` after a commit.
1734
+
1735
+ - **No node for the plugin.** Naming the path-loaded plugin's own package, which the lockfile did not list, failed the hash: "The externalDependency '@exp/nxr' for 'a:t' could not be found". The executor's package, which `pnpm-lock.yaml` lists, had a node, but no longer once `pnpm-lock.yaml` was listed in `.gitignore` and taken out of the index, and naming it then failed in the same way. As read in the installed source, Nx creates npm nodes only from a lockfile in its file map, and its lockfile analysis is off when `pluginsConfig["@nx/js"].analyzeLockfile` is `false`, and by default, unless `nx.json` sets it, without a root `package.json` or with a `lerna.json` and no `nx.json` (`plugins/js/index.js`, `plugins/js/utils/config.js`).
1736
+ - **What of a project's configuration Nx hashes.** A changed value in the options of `t` changed the key of `a:t`, and so did one in the options of `u`, in the configurations of `t`, in the project's tags and in `parallelism` of `t`. A change in the `metadata` of `t` or of the project, a named input that no target used, `dependsOn` or `cache` did not. With `externalDependencies: []`, a value standing for the plugin's version in the options of `t` changed the key from one version to the next, and hashing did not fail.
1737
+ - **A value that takes the plugin's place.** Checked on the same day in this repository's fixture harness, in `subfolder-workspace` with the plugin loaded by path, Nx's lockfile analysis off and the plugin's own version changed from 1.0.0 to 1.0.1 between two hashes of `api:test`, before graph creation rejected such values. With `pluginVersion: "0.0.0"` given to every target of `api` and of the crates whose configuration the key of `api:test` holds, by a `targetDefaults` entry for each of the plugin's two executors, by a `project.json` in each crate's folder or by a `package.json` there that the root `package.json`'s `workspaces` lists, the key stayed the same. Given to `test` alone, by `targetDefaults`, in a configuration, a `project.json` or a `package.json`, and given on the command line, the value left the project configurations of `api`, `codegen`, `model` and `testkit` changed, and so the key. A `package.json` in a crate's folder that no `workspaces` lists did not reach the project.
1738
+ - **The package's dependencies.** With `externalDependencies: ["@exp/executor"]`, the key held `npm:tslib@2.9.1` as well, and a changed integrity of `tslib` in `pnpm-lock.yaml` changed it. A changed integrity of `@clack/core`, on which the executor's package does not depend, left it unchanged.
1739
+ - **nx affected after a JS lockfile change.** Under Nx's default `projectsAffectedByDependencyUpdates`, which is `all` (`plugins/js/utils/config.js`), the commit that changed `@clack/core` selected `a:t` and `b:t` with the reason `moved-ecosystem` for `npm`, although their keys had not changed; with `externalDependencies: []` it selected neither. With `"projectsAffectedByDependencyUpdates": "auto"` in the `@nx/js` section of `pluginsConfig`, that commit selected neither, and a commit that changed `tslib` selected both, with `npm:tslib@2.9.1` as the reason.
1740
+ - **Uncached targets and a project at the repository root.** Checked on the same day in this repository's fixture harness, in `two-workspaces` with a root `package.json` and `pnpm-lock.yaml`: one workspace lies at the repository root, with its workspace project at root `.`, the other in `tools/`. After a commit that changed only the integrity of `left-pad`, on which the plugin's package does not depend, `nx affected -t test --explain=stdout` reported both lockfile tasks, which then had no `externalDependencies` input, as touched with the reason `external-dependencies`, under `all` and `auto` and whatever the crate targets declared, and every crate's `test` task as affected through their outputs (`dependent-output`). With an `externalDependencies` input on the lockfile tasks, nothing of `tools/` was selected. The lockfile task at the root stayed touched, with the reason `project-configuration` for `pnpm-lock.yaml`, which matches the `createNodes` pattern of Nx's own `nx/js/dependencies-and-lockfile` plugin and lies in that project's folder, and so did that project's `audit`, `update` and `doc`.
1741
+ - **Keys of a project at the repository root.** Checked on 14 November 2026 with Nx's own task hasher in this repository's fixture harness, in `two-workspaces` with a root `package.json` and `pnpm-lock.yaml`: once as the fixture is, with the virtual workspace's project `cargo-workspace` at root `.`, and once with a package `rootpkg` added to the root manifest, whose project at `.` then holds the workspace's targets. Nx's JS plugin had drawn a static edge from the project at `.` to `npm:left-pad`, which the root `package.json` lists. A change of only the integrity of `left-pad` changed the keys of `cargo-workspace:doc` and of every cached target of `rootpkg`, with the plugin's package listed in the lockfile and without it; the hash details named the project's fileset `{projectRoot}/**/*` without `Cargo.lock`, and `npm:left-pad`. A change of only the `description` of the root `package.json` changed the same keys, through the fileset alone. The lockfile task at the root, `app:test`, `util:test`, `tools:test` and `tools:doc` kept their keys in every case, and so did `app:build`, `app:check`, `app:lint`, `app:fmt-check` and `scaffold:test` in the first layout. In the review of the same day, with `app` depending on `rootpkg` by path, a change of only the integrity of `left-pad` also changed the keys of `app:test` and `app:build`, whose `^default` holds `rootpkg`'s fileset, while the lockfile task at the root, `util:test`, `tools:test` and `tools:doc` kept theirs. Changing only `targets.test.metadata.description` in a `project.json` in `crates/app` changed the keys of `app:test` and `app:build`, and the hash details named only the project's fileset, which holds that file, and not its configuration.
1742
+ :::
1743
+
1744
+ :::mara evidence EVD-NX-24-LOCKFILE-TASK
1745
+ :mid: 01M7ACCPE3Z4TVZ0EBZZVXR4PP
1746
+ :title: How a lockfile task keys crates and drives nx affected in Nx 24.0.6
1747
+ :status: accepted
1748
+ :supports: ADR-LOCKFILE-TASK
1749
+ :supports: DES-LOCKFILE-HASHING
1750
+ :supports: DES-INPUTS
1751
+ :supports: REQ-NO-RUST-TASK-DEPS
1752
+
1753
+ Experiments on 13 November 2026 with the versions of [[EVD-NX-24-EXTERNAL-NODES]] and cargo 1.100.0, in throwaway workspaces outside this repository. In these runs the lockfile task was cached and wrote its digests without running cargo; [[EVD-NX-24-LOCKFILE-UPDATE]] has the task as it is now.
1754
+
1755
+ The first was the workspace of that item without its external nodes. A project at `rust/` had a cached `nx:run-commands` target that read `rust/Cargo.lock` and wrote, into a git-ignored folder, one file per crate holding a SHA-256 over the name, version, source and checksum of every package the crate's lockfile entry reaches. Each crate had a cached target that depended on it and declared `{ "dependentTasksOutputFiles": "<folder>/<crate>.digest" }` and `externalDependencies: []` besides its own files and a `^` input over them.
1756
+
1757
+ The second held a Cargo workspace at `rust/` whose root manifest also is the package `root`, with the members `a`, which depends on `itoa`, `b`, which depends on `ryu`, and `c`, which depends by path on `a` and on `root`. The project of `root` carried the lockfile task. Every crate had a cached `test` target that depended on it and read the crate's digest as in the first workspace, run by an executor from a local package with a `batchImplementation` and `preferBatch: true` that logged its calls. The lockfile task and the `test` targets named that package in `externalDependencies`. A crate's own files were the input `{projectRoot}/**/*` with `!{projectRoot}/Cargo.lock`, unless a case says otherwise. Bumps came from `cargo update -p <crate> --precise <version>`, and every run was `nx run-many -t test --outputStyle=static` with `NX_DAEMON=false`, except where the daemon was started with `nx daemon --start`.
1758
+
1759
+ - **Keys.** A bump changed the keys of exactly the crates that reach the package. In the first workspace, a bump of `serde_derive`, which `a` and `c` reach only through `serde`, ran `a` and `c` and restored `b` from the cache, and a bump of `itoa` did the reverse. In the second, a bump of `itoa` ran `a` and `c`, and one of `ryu` ran `b` only. The lockfile task ran again after every bump.
1760
+ - **Affected.** After a commit that changed only the lockfile, `nx affected -t test` selected the lockfile task through `rust/Cargo.lock` and every crate task of the workspace, with the reason `dependent-output` and the lockfile task as producer. Running it executed the crates whose digest had changed and restored the others from the cache.
1761
+ - **Batching.** The lockfile task ran first and on its own. The four `test` tasks then reached the executor as one batch, and after a bump only those that had to run did, again as one batch.
1762
+ - **Where the digests live.** With the digests in `.nx/workspace-data/nx-rust/<workspace>`, in `node_modules/.cache/nx-rust/<workspace>` or in the artifact directory `rust/target/nx-rust/lockfile`, a second run restored every task from the cache. After the folder was deleted, the next run restored the lockfile task from the cache, its files included, and every crate task with it. `git status` showed nothing new in any of the three. With the folder outside the repository, the lockfile task ran again after a bump of `itoa` and wrote a new digest, but `a` and `c` were restored from the cache: Nx did not hash a dependency's output that lies outside the workspace. With the daemon on and the digests in `.nx/workspace-data`, the runs gave the same results as without it.
1763
+ - **Root package.** Without `!{projectRoot}/Cargo.lock`, the files of `root` included `rust/Cargo.lock` and no file of a member, and a bump of `ryu`, which only `b` reaches, ran `root` and `c`, which depends on `root`, besides `b`. With it, only `b` ran.
1764
+ - **Git-ignored lockfile.** With `Cargo.lock` listed in `rust/.gitignore` and removed from the index, a plain file input did not see a bump: the lockfile task was restored from the cache with the old digests, and every crate task with it. With `{ "fileset": "{projectRoot}/Cargo.lock", "includeIgnored": true }`, the lockfile task ran again, and `a` and `c` after it.
1765
+
1766
+ A third workspace on the same day tried a comparison, written by the plugin, of each lockfile entry with the dependencies that the manifests declare, with one digest over the whole lockfile and the declarations for every crate whenever they differed. It ran `a`, `b` and `c` where digests over the stale lockfile alone had restored `a` and `c` after a member's new requirement. The review of pull request #14 then found states it missed, and cargo's own check replaced it ([[EVD-CARGO-LOCK-CHECK]]). In that workspace, with the task still cached, a deleted or overwritten digest folder came back with the task from the cache.
1767
+
1768
+ `nx init` writes `.nx/workspace-data` into `.gitignore` (`command-line/init/implementation/utils.js`), and a comment in `daemon/server/restart-checks.js` calls that folder hardcoded-ignored by the daemon's file watcher; both were read, not run. No cargo build ran inside Nx: the executors only logged.
1769
+ :::
1770
+
1771
+ :::mara evidence EVD-CARGO-LOCKFILE
1772
+ :mid: 01M7ACCPE3XWH5NE1AJ970AVQH
1773
+ :title: What Cargo.lock records, and how a build of the whole workspace unifies features
1774
+ :status: accepted
1775
+ :supports: DES-LOCKFILE-HASHING
1776
+ :supports: DES-INPUTS
1777
+
1778
+ An experiment on 13 November 2026 with cargo and rustc 1.100.0 on Linux x86-64, outside this repository, with crates.io reachable. The workspace had the members `a`, `b`, `f1` and `f2`. `a` had a normal dependency on `itoa = "1"`, an optional one on `smallvec` that no feature enabled, `ryu` as a dev-dependency, `cfg-if` as a build dependency and `memchr` under `[target.'cfg(windows)'.dependencies]`. `b` depended on `itoa = "0.4"`, on a crate in a local git repository and by path on `v`, a crate outside the workspace that depends on `ryu`. `f1` and `f2` depended by path on `x`, a crate outside the workspace with a feature `f` and a function that returns `cfg!(feature = "f")`. `f2` enabled `f` and `f1` did not; `f1` was a binary that printed the function's result. `cargo generate-lockfile` wrote the lockfile.
1779
+
1780
+ - **A member's entry.** The entry of `a` listed `cfg-if`, `itoa 1.0.19`, `memchr`, `ryu` and `smallvec`: its normal, dev and build dependencies, the dependency for another platform and the optional one that nothing enabled. The lockfile records no features.
1781
+ - **Several versions.** `itoa` was locked at 0.4.8 and at 1.0.19, and an entry names such a dependency with its version, as in `"itoa 0.4.8"`.
1782
+ - **Sources.** A registry package had a `source` and a `checksum`. The git dependency had `source = "git+file:///…#<commit>"`, ending in the commit, and no checksum.
1783
+ - **Path packages.** `v` and `x` had neither `source` nor `checksum`, and the entry of `v` listed `ryu`.
1784
+ - **Features of another member.** `cargo run -p f1` printed `false`. After `cargo build --workspace`, `target/debug/f1` printed `true`: built together with `f2`, `x` had the feature that `f2` enables.
1785
+
1786
+ `x` is a path crate. Cargo's resolver unifies the features of a registry crate in the same way, which this experiment did not run.
1787
+
1788
+ A second experiment on the same day used a workspace with the members `a`; `b`, which depends on `itoa = "1"` and by path on `v`, a crate outside the workspace with `cfg-if` as a dependency and `ryu` as a dev-dependency; and `c`, which depends on `a`. `cargo update -p itoa --precise` wrote two lockfiles, with `itoa` at 1.0.17 and at 1.0.19.
1789
+
1790
+ - **Dev-dependencies of other path packages.** The entry of `v` listed `cfg-if` and not `ryu`, and no `ryu` was locked: a lockfile records the dev-dependencies of workspace members only.
1791
+ - **Stale lockfile.** With `itoa = "1"` added to the manifest of `a` and either lockfile in place, the entry of `a` listed nothing. `cargo build -p a` rewrote the lockfile, gave `a` an `itoa` dependency and kept the version that lockfile had locked, 1.0.17 or 1.0.19.
1792
+ - **A sibling.** With `itoa = "=1.0.10"` in the manifest of `a` and the lockfile with 1.0.19, whose entry for `b` matched `b`'s manifest, `cargo build -p b` resolved the workspace again, and `cargo tree -p b` then showed `itoa` 1.0.10.
1793
+ :::
1794
+
1795
+ :::mara evidence EVD-CARGO-LOCK-CHECK
1796
+ :mid: 01M7ANS8X2N5DQ2844PTFSYCA0
1797
+ :title: How cargo judges and updates Cargo.lock, and what a current lockfile fixes
1798
+ :status: accepted
1799
+ :supports: DES-LOCKFILE-HASHING
1800
+ :supports: ADR-LOCKFILE-TASK
1801
+
1802
+ Experiments on 13 November 2026 with cargo 1.100.0 and 1.91.0 on Linux x86-64, crates.io reachable, re-run in the fixtures of the lockfile research for this issue. One workspace has the members `a` (`smallvec`, `itoa = "1"`), `b` (`serde`, `ryu`, a git dependency and `v`, a path crate outside the workspace) and `c` (`a`); each case was applied to its committed, current state. Another uses a local registry in which versions can be published. The digest is the closure of [[DES-LOCKFILE-HASHING]], computed by a script from `Cargo.lock`, and the packages compiled for a crate came from `cargo check -p <crate> --message-format json`.
1803
+
1804
+ - **The verdict.** In each state, `cargo update --workspace --locked`, `cargo metadata --locked` and `cargo check --workspace --locked` agreed. All three exited 0 for the committed state and for a removed member. They exited 101 for a requirement in `b` that moves a version `a` shares (`itoa = "=1.0.10"`), a feature in `a` that adds packages (`smallvec` with `serde`), an added `[replace]`, a same-version `[patch]` in `$CARGO_HOME/config.toml` and an unsatisfied requirement, on 1.100.0 and, for the first three, on 1.91.0. The message contains "--locked was passed to prevent this" on both. The research found the same agreement in 27 states on both toolchains, and that the check needs only the index entries of the locked packages, writes nothing to the repository or the build directory, and took 22 to 250 ms on a warm cargo home and up to 1.7 s, 4.5 s with 1.91.0, on a cold one with 493 locked packages.
1805
+ - **The update.** For 14 stale states and a missing lockfile, `cargo update --workspace` wrote the same bytes as plain `cargo check --workspace`. The stale states were a removed dependency, an unsatisfied requirement, the sibling's requirement, the feature, `[patch]` in the root manifest, in the repository's and in the cargo home's configuration, a newer-version `[patch]`, `[replace]`, a new version and a new dependency of `v`, a `branch` on the git dependency, and an added member. On the current lockfile it wrote nothing and kept the file's modification time.
1806
+ - **Digests.** After the update, the digest of `a` followed what `a` compiles: `itoa` 1.0.10 after the sibling's requirement, the path crate after `[replace]` and after the cargo-home `[patch]`, and a closure with `serde` after the feature. In every state, the packages compiled for `a` and `b` lay inside their closures. Without following `replace = …`, the digest of `a` stayed the same with `[replace]`, while `a` compiled the path crate. With a member removed, plain `cargo check` rewrote the current lockfile, and the digests of the remaining members stayed the same.
1807
+ - **Identical files, two resolutions.** In the local-registry workspace, with `yylib = "1"` added to a manifest and the lockfile not updated, all files hashed alike in two runs. `cargo update --workspace` added `yylib` 1.0.0 while the registry held only that version, and 1.0.1 once it was published, and the crate's digest changed with it. `--locked` called the lockfile stale both times.
1808
+ - **cargo fmt.** `cargo fmt` and `cargo fmt --check` left a stale lockfile unchanged with both toolchains.
1809
+ - **Edges.** In a local registry with `zzlib` 1.0.0 and 2.0.0 and a `wrapper` that depends on `zzlib >=1, <3`, a binary depending on both `zzlib` versions and on `wrapper` was locked once with `wrapper` on `zzlib` 2.0.0 and once, by editing that entry, on 1.0.0. `cargo update --workspace --locked` exited 0 in both states with both toolchains, `cargo run --locked` printed `1 2 2` and `1 2 1`, and a digest over the packages alone was the same in both. The digest that also covers each entry's dependency strings differed. With it, the cases above changed the same digests as before.
1810
+
1811
+ The research also found that a `paths` override in `.cargo/config.toml` is compiled while cargo calls the lockfile current and leaves no trace in it; that was not re-run.
1812
+ :::
1813
+
1814
+ :::mara evidence EVD-NX-24-LOCKFILE-UPDATE
1815
+ :mid: 01M7ANS8X2BSA42J4X4E6QFP0R
1816
+ :title: How Nx 24.0.6 runs an uncached lockfile task that lets cargo update Cargo.lock
1817
+ :status: accepted
1818
+ :supports: DES-LOCKFILE-HASHING
1819
+ :supports: ADR-LOCKFILE-TASK
1820
+ :supports: DES-INPUTS
1821
+
1822
+ Experiments on 13 November 2026 with `nx` 24.0.6, Node 26.12.0 and cargo 1.100.0, with `NX_DAEMON=false`, re-run in the Nx workspace of the lockfile research for this issue. Its Cargo workspace `rust/` has the members `a` (`smallvec`, `itoa = "1"`), `b` (`serde`, `ryu`, `itoa = "=1.0.10"`, `memchr`) and `c` (`a`). The project `rust` had an uncached `lockfile` target that ran `cargo update --workspace`, with `--locked` under `NX_RUST_LOCKED=true`, and then wrote the closure digest of each member into `.nx/workspace-data/nx-rust/lockfile/rust`, declared as its outputs. Its inputs were `Cargo.lock` with `includeIgnored`, the root manifest and `{workspaceRoot}/rust/*/Cargo.toml`. Each crate had a cached `check` target that depended on it, ran `cargo check -p`, and hashed its digest through `dependentTasksOutputFiles`. With `POSTCHECK=digest`, it computed the crate's digest again after its call and failed when that differed from the digest file.
1823
+
1824
+ - **Every run.** On a second run with nothing changed, the lockfile task ran and every crate was restored from the cache.
1825
+ - **A stale lockfile.** With `b`'s requirement changed to `itoa = "=1.0.11"`, the lockfile task printed cargo's "Updating itoa v1.0.10 -> v1.0.11", and `a`, `b` and `c` ran on new digests. With the manifest and the lockfile reverted, all three were restored. When the task wrote digests from the stale lockfile without running cargo, only `b` ran: `a` and `c` were restored, although `a` compiles the new `itoa`.
1826
+ - **Locked mode.** With `NX_RUST_LOCKED=true` and the stale lockfile, the lockfile task failed with cargo's message. Nx listed the crate tasks under "Tasks not run because their dependencies failed" and exited 1, and `Cargo.lock` was unchanged.
1827
+ - **A plain file input.** A cached target that depended on the lockfile task and had `Cargo.lock` as a plain file input was restored, in the run in which the task rewrote the lockfile, with its result for the old lockfile. It ran on the next run.
1828
+ - **Post-check.** With `b`'s manifest changed while `a`'s cargo call ran, cargo rewrote `Cargo.lock` during that call, and the digest of `a` no longer matched its digest file. The task failed, and Nx stored nothing for it. The next run ran `a`, `b` and `c` on the new digests.
1829
+ - **nx affected.** A commit that changed only `b/Cargo.toml` selected `rust:lockfile`, `a:check`, `b:check` and `c:check`.
1830
+ - **Excluded dependencies.** Without help, the review of pull request #14 found, `nx run a:check --exclude-task-dependencies` was restored from the cache after `cargo update -p smallvec --precise 1.15.1`. A stand-in `preTasksExecution` hook parsed the command's arguments with Nx's own `yargs-parser` and set an environment variable to a new value when they excluded task dependencies, and to the empty string otherwise. The crates' `check` targets had it as an `env` input. After a normal run, `nx run a:check --exclude-task-dependencies` ran `a`, and after `cargo update -p smallvec --precise 1.15.1` the same command ran it again. `nx run-many -t check --excludeTaskDependencies` and `nx affected -t check --exclude-task-dependencies=true` ran their tasks too, and `--no-exclude-task-dependencies` gave a normal run. A normal run afterwards restored every task, with the daemon off and on, and the keys of normal runs were the same in both modes. With the variable unset and the hook not setting it, a normal run was restored as well.
1831
+ - **What Nx stores.** As read in `tasks-runner/task-orchestrator.js`, Nx stores a result only when the task is cached and its exit code is 0, or with `NX_CACHE_FAILURES=true` whatever the code. Failing is the only way for a task to keep its result out of the cache.
1832
+
1833
+ The research also reported, without a re-run here: inputs written as `{projectRoot}/*/Cargo.toml` missed the members' manifests, which belong to nested projects; and with the task cached and its inputs complete, a `[patch]` in `$CARGO_HOME/config.toml` let the task, `a` and `c` be restored although cargo called the lockfile stale.
1834
+ :::
1835
+
1836
+ :::mara evidence EVD-CARGO-DEP-INFO
1837
+ :mid: 01M7ACMK1Q7ATJKRRHC2WPJE1Z
1838
+ :title: Where Cargo records the files that build scripts and macros read
1839
+ :status: accepted
1840
+ :supports: ADR-DECLARED-FILE-INPUTS
1841
+ :supports: DES-BUILD-INPUT-CHECK
1842
+ :supports: RISK-UNDECLARED-INPUTS
1843
+
1844
+ Experiments on 13 November 2026 with cargo and rustc 1.100.0 (cargo 3acc79c0c 2026-11-05) and, where named, cargo 1.98.1, 1.97.1 and 1.91.0, on Linux x86-64, in throwaway folders outside this repository, with no Cargo configuration in the home folder and no toolchain pinned. The fixture was a virtual workspace `ws` with the members `app` and `dep`, beside the folders `proto`, `shared` and `assets` outside it. `app` depended on `dep` by path. Its build script printed `cargo::rerun-if-changed` for `../../../proto/app.proto`, for the folder `../../../assets` and for `build.rs`, read the proto file and set a variable with `cargo::rustc-env`; its library used `include_str!` on `shared/data.txt`, its binary called the library, and an integration test used `include_bytes!` on `shared/test-data.bin`. `dep`'s build script named `../../../proto/dep.proto`, and its library included `shared/dep.txt`. Later steps added `pm`, a proc-macro crate whose macro read `shared/pm.txt` with `std::fs`, used by `app2`, which also depended on the registry crate `libc` (built with `--offline` from the local registry cache); `gen`, whose build script wrote a file into `OUT_DIR`, which its library included with `include!`, and named `/etc/hostname`; and `cd`, with the crate types `cdylib`, `rlib` and `staticlib`, whose library included a file with a space in its name.
1845
+
1846
+ - **check, clippy, test and doc.** After `cargo check --workspace`, `cargo clippy --workspace --all-targets`, `cargo test --workspace --no-run` and `cargo doc --workspace`, `find target -name '*.d'` showed dependency files only under `target/debug/build/<package>/<hash>/out/`, in the build directory of the default layout, and none in `target/debug` itself or in `target/doc`. The build script's `rerun-if-changed` lines were in `build/<package>/<hash>/run/stdout`, and its fingerprint `run-build-script-build-script-build.json` listed the paths under `RerunIfChanged`, relative to the package's folder. rustc's dependency file for the library, `out/app-<hash>.d`, listed `crates/app/src/../../../../shared/data.txt` beside the source, and an `# env-dep:PROTO_LEN=7` line. The file that the integration test included appeared only in the test's dependency file in the build directory.
1847
+ - **build.** `cargo build --workspace` also wrote `target/debug/app.d`, `libapp.d` and `libdep.d` beside the binary and the `rlib` files, in Makefile syntax with absolute paths. `app.d` listed both proto files, the `assets` folder as one path, both build scripts, both included text files and the sources of `app` and `dep`; `libdep.d` listed only `dep`'s files. None listed the file of the integration test. With `build.build-dir` set to a folder outside the workspace, the three files stayed in `target/debug`, and every other dependency file was in the build directory. With cargo 1.97.1 and the same setting, `cargo build --workspace` wrote the three files in `target/debug` as well, and the build script's record lay at `<build directory>/debug/build/app-<hash>/output` instead.
1848
+ - **More of build.** `app2.d` listed the sources of `app2` and `pm` and no file of `libc`. `libgen.d` listed `/etc/hostname` and the generated file under `target/debug/build/`. For `cd`, Cargo wrote `libcd.a`, `libcd.rlib`, `libcd.so` and a single `libcd.d`, which escaped the space as `with\ space.txt`. After a change to `app`'s library, `cargo build -p app` wrote `app.d` and `libapp.d` again and not `libdep.d`. After `app.d` was deleted, `cargo build -p app` compiled nothing and wrote it again. With `--config build.dep-info-basedir=<folder>`, the paths were relative to that folder.
1849
+ - **Fresh builds.** Whether a build that compiles nothing gives the records a new time differs between versions and crates. In a second workspace with three crates, one without a build script, one whose build script named only `build.rs` with `rerun-if-changed`, and one whose build script named a folder, two further `cargo build --workspace` runs with cargo 1.100.0 kept the time of all three records; with cargo 1.98.1 and 1.97.1 they kept the time of the crate without a build script and gave the other two new times. In the first fixture, cargo 1.100.0 gave `app.d` and `libapp.d` a new time on each of three fresh builds of `app`. With all three versions, a deleted record was there again after the next build, which compiled nothing. A record is thus present after every successful build, and its time says nothing about that build.
1850
+ - **Stale records.** `cargo build -p dep` wrote `libdep.d` for the library-only crate `dep`, listing `proto/dep.proto` and `shared/dep.txt`. After `app` got a second binary `extra` with `required-features = ["x"]`, `cargo build -p app --features x` wrote `extra.d`, and a later `cargo build -p app` left it with its old time. `cargo build -p app --release` and `cargo build -p app --target x86_64-unknown-linux-gnu` wrote `app.d` and `libapp.d` in `target/release` and `target/x86_64-unknown-linux-gnu/debug`, beside those in `target/debug`. A crate `wide` whose build script printed `cargo::rerun-if-changed=../..` got `crates/wide/../..`, the workspace folder that holds `target`, as one path in `libwide.d`.
1851
+ - **Which records a build exports.** A third workspace, built with debug information and incremental compilation off to save space, had a library-only crate `lib-only`; a crate `multi` with the library `multicore`, the binaries `one`, `two-dash` and `three`, the last with `required-features = ["extra"]`, and a feature `full = ["extra"]`; a crate `cd` with the crate types `cdylib` and `staticlib`; a proc-macro crate `pm`; and a profile `fast` that inherits `release`. A script named the records that `cargo build -p <crate>` should export from the `cargo metadata --no-deps` report and the build's features, profile and triple, and compared them, in thirteen builds, with the files outside the build directory that the `compiler-artifact` messages of the same build with `--message-format=json` named, the messages serving only as a check. Every build agreed: `multi` without features, with `--features extra`, `--features full` and `--all-features`, with `--release`, `--profile fast` (folder `target/fast`), `--target x86_64-unknown-linux-gnu` alone and with `--release` (folder `target/x86_64-unknown-linux-gnu/<profile>`), and with `CARGO_BUILD_TARGET` set to that triple and no `--target` (the same folder); `lib-only`; `cd` in `dev` and `release`; and `pm`. The library's record was `lib<name>.d` with `-` replaced by `_` (`liblib_only.d`, `libmulticore.d`, `libcd.d`, `libpm.d`), a binary's kept its name (`two-dash.d`), and `three.d` was exported exactly when `extra` was on.
1852
+ - **The naming matrix.** A fourth workspace had eight crates: libraries of the crate types `rlib` (the crate `k-rlib`), `cdylib`, `staticlib`, all three together, and `proc-macro`; a crate with a binary only; one with a library and the binary `k-libbin-cli`; and a proc macro with a binary. Its root manifest defined the profiles `c_dev`, `c_release`, `c_test` and `c_bench`, each with `inherits` naming the profile of that name without `c_`. Each crate was built on its own with `cargo build -p <crate> --profile <profile> --message-format=json` for each of the eight profiles, under each triple mode: no triple, `--target x86_64-unknown-linux-gnu` (the host), `--target x86_64-unknown-linux-musl` (with 1.100.0, the only toolchain with another triple installed), `CARGO_BUILD_TARGET` set to the host triple, and `[build] target` set to the host triple in `.cargo/config.toml`. For every build, a script named the records from the `cargo metadata --no-deps` report, the profile and the triple, and compared them with the files that the `compiler-artifact` messages named outside the build directory, the messages serving only as a check. With cargo 1.100.0, 256 of 320 builds agreed. The 56 builds where the configuration chose the triple differed for every crate but the plain proc macro: cargo wrote the records to `target/x86_64-unknown-linux-gnu/<profile>`, and the names, which knew no triple, pointed at `target/<profile>`. In those builds a record of the same name lay in the triple folder after the call, and a proc macro's library record, in `target/<profile>`, agreed. For the `cdylib`-only crate and the musl triple, the 8 builds failed with "cannot produce cdylib … as the target `x86_64-unknown-linux-musl` does not support these crate types"; for the crate with all three types, cargo warned "dropping unsupported crate type `cdylib`" and wrote `libk_multi.d`, as named. With cargo 1.91.0, 200 of 256 builds agreed, and the other 56 were the configured-triple builds again. Together the builds showed: a proc macro's library record lies in `target/<profile folder>` whatever the triple, while a binary of the same crate follows the triple; `test` writes to `debug` and `bench` to `release`, like `dev` and `release`; and a custom profile writes to a folder of its own name, whichever profile it inherits from. In the shared target folder, once a build for a named triple had left a record of the same name there, the check's guard for a triple it cannot know also skipped the host-folder records of 14 later builds without a triple, with each toolchain.
1853
+ - **Records after a change.** In fresh workspaces with one crate and the files `old.txt`, `new.txt`, `a.txt` and `b.txt` beside it, with cargo 1.91.0 and 1.100.0 alike: an `rlib` that included `old.txt`, built with `--target x86_64-unknown-linux-gnu`, then turned into a proc macro that included `new.txt` and built the same way, left `target/x86_64-unknown-linux-gnu/debug/libc.d` listing `old.txt` and wrote `target/debug/libc.d` listing `new.txt`; turned back into an `rlib` that included `old.txt`, it wrote the triple folder's record again, listing `old.txt`, and left the host folder's listing `new.txt`. A `--release` build that included `old.txt`, followed by a change to `new.txt` and a `dev` build, left `release/libc.d` listing `old.txt` and wrote `debug/libc.d` listing `new.txt`; the same held for a build with `--target` followed by one without. A crate with a feature `x` that included `a.txt` with it and `b.txt` without it, built with `x`, without, with `x` and with `x` again, compiled one unit, one, none and none, and `debug/libc.d` listed `a.txt`, `b.txt`, `a.txt` and `a.txt`: a record follows the call's feature set also when nothing compiles. After a binary `two` was removed from the manifest, the next build left `debug/two.d` in place.
1854
+ - **Features of binaries.** On 14 November 2026, with cargo 1.100.0 and 1.91.0 alike, a workspace's crate `p` had the optional path dependencies `a`, `b` and `c`, the features `default = ["chain1"]`, `chain1 = ["chain2"]`, `chain2 = ["chain3"]`, `chain3 = []`, `full = ["a/x"]`, `deep = ["full"]`, `weak = ["b?/x"]` and `viadep = ["dep:c"]`, and binaries that required `a`, `b`, `chain3` and `full`. `cargo metadata --no-deps` listed the implicit features `a = ["dep:a"]` and `b = ["dep:b"]`, and none for `c`. The `compiler-artifact` messages of `cargo build -p p` showed the binary that requires `a` built with `--features full`, `--features a/x`, `--features a`, `--features p/full`, `--features deep --no-default-features` and `--all-features`, and not with `--features weak`, `--features b?/x`, `--features a?/x,b` or `--features viadep`; `--features weak,b` built the one that requires `b`, and `--no-default-features` alone built none. With a feature `a = []` beside a dependency `a` that was not optional, `--features full` left that feature off.
1855
+ - **Where such names fall short.** With `[build] target = "x86_64-unknown-linux-gnu"` in `.cargo/config.toml` and no `--target`, `cargo build -p multi` exported its records to `target/x86_64-unknown-linux-gnu/debug`, while an older `target/debug/one.d` remained. `cargo build -p multi -p user`, where `user` depends on `multi` with `features = ["extra"]`, built and exported `three` as well. Two crates `cola` and `colb` with a binary `cli` each, built in one call, gave the warning "output filename collision" and one `cli.d`, which listed only `colb`'s source. `cargo build -p multi --bin one` reported the library only by its files in the build directory and exported only `one.d`, which listed the library's source beside the binary's.
1856
+ - **Files of a separate build directory with 1.91.** On 20 November 2026, in a copy of this repository's fixture `undeclared-files`, whose crate `reader` includes with `include!` the file `lines.rs` that its build script writes into `OUT_DIR`, `cargo build -q -p reader` with the build directory `bd` in the workspace folder, set as `CARGO_BUILD_BUILD_DIR=bd`, as that variable with an absolute path, and as `build-dir = "bd"` in `.cargo/config.toml`, put `OUT_DIR` and the generated file in the build directory with every toolchain, in `bd/debug/build/reader-<hash>/out` with cargo 1.91.0, 1.97.1, 1.98.1 and 1.99.0 and in `bd/debug/build/reader/<hash>/out` with 1.100.0, and `cargo metadata --no-deps` reported `bd` as the build directory. With cargo 1.97.1, 1.98.1, 1.99.0 and 1.100.0, `target/debug/libreader.d` named the file there. With cargo 1.91.0 it named `target/debug/build/reader-<hash>/out/lines.rs`, the file's path below the build directory placed below the artifact directory, where nothing was, and `target/debug/build` did not exist; a second build compiled nothing. Cargo 1.91 stores the paths of a target's dependency file in the build directory relative to the build directory, and when it exports the record it joins them to the artifact directory instead: `output_depinfo.rs` of cargo 0.92.0 (Rust 1.91) passes `host_root()`, the artifact directory, to `parse_dep_info`, while `translate_dep_info` stored the paths relative to the build directory. Cargo 0.93.0 (Rust 1.92) passes `host_build_root()`, changed by rust-lang/cargo#16092, merged on 13 October 2025 for 1.92.0. A path that the build script names with `rerun-if-changed`, which Cargo exports from the build script's output and not from that file, was named in `bd` by 1.91.0 too, beside the misplaced one. Where the build directory is the artifact directory, as by default, the two joins agree, which is why the generated file appeared under `target/debug/build/` above. The harness's run of `nx run reader:build` with the variable in the crate's `.env` gave cargo `CARGO_BUILD_BUILD_DIR=bd`, the workspace folder as its working directory and the same `OUT_DIR` in `bd` with both versions, so the task's cargo received what plain cargo did.
1857
+ - **Links.** A crate `linky` whose library used `include_str!` on `shared/alias.txt`, a symbolic link to `shared/data.txt`, got the link's spelling `crates/linky/src/../../../shared/alias.txt` in `liblinky.d`. After `data.txt` changed, `cargo build -p linky -v` reported `linky` dirty, naming that path, and compiled it again.
1858
+ - **JSON messages.** `cargo build --workspace --message-format=json` gave `build-script-executed` messages with the keys `cfgs`, `env`, `linked_libs`, `linked_paths`, `out_dir`, `package_id` and `reason`, and `compiler-artifact` messages whose `filenames` held the artifacts and no dependency file. No message named a `rerun-if-changed` path.
1859
+ - **What Cargo tracks.** After `proto/app.proto` changed, the next `cargo build` ran `app`'s build script and compiled `app` again. `cargo build -p app -v` reported `app` dirty, naming the path `crates/app/../../../assets`, after a file in that folder changed and again after a file was added to it. After `shared/pm.txt` changed, `cargo build -p app2` finished in 0.00s without compiling, and the binary still printed the old content: Cargo does not track a file that a proc macro opens itself.
1860
+ - **Build helpers.** In the sources in the local registry, tauri-build 2.6.3 prints `cargo:rerun-if-changed` for paths it computes from its configuration (`src/codegen/context.rs`, from line 91), and bindgen 0.72.1 prints it for the headers that a binding includes (`lib.rs`, lines 1302 and 1307). include_dir 0.7.4 tracks a folder only with its `nightly` feature, through `proc_macro::tracked_path`, and otherwise expands to an `include_bytes!` per file (`include_dir_macros/src/lib.rs`).
1861
+ - **Documentation.** The Cargo book of the 1.100.0 toolchain (`reference/build-cache.html`, "Dep-info files") says that the file with the `.d` suffix next to each compiled artifact indicates the files the artifact depends on, that these files are "intended to be used with external build systems", and that their paths are absolute unless `build.dep-info-basedir` is set. The same page calls the intermediate artifacts in the build directory "internal to Cargo and the Rust compiler".
1862
+
1863
+ The workspace was a toy on Linux, so the names of macOS libraries, such as `.dylib`, were not seen.
1864
+ :::
1865
+
1866
+ :::mara evidence EVD-NX-24-FILE-INPUTS
1867
+ :mid: 01M7ACMK1QCT1DZYXHK8C0D50R
1868
+ :title: How Nx 24.0.6 treats files outside a project and stores task results
1869
+ :status: accepted
1870
+ :supports: ADR-DECLARED-FILE-INPUTS
1871
+ :supports: DES-INPUTS
1872
+ :supports: DES-BUILD-INPUT-CHECK
1873
+
1874
+ Experiments on 13 November 2026 with the `nx` 24.0.6 package installed in this repository, linked into a throwaway git repository outside it, with Node.js 26.12.0 and git 2.56.0, and a reading of that package. Nx ran as `node node_modules/nx/dist/bin/nx.js` with `NX_DAEMON=false`, `NX_NO_CLOUD=true` and `NX_TUI=false`. The repository had two projects whose cached `build` target ran `echo` through `nx:run-commands`: `a`, with the inputs `{projectRoot}/**/*` and the runtime input `sha256sum shared/a.txt`, and `b`, with `{projectRoot}/**/*` and a fileset for `{workspaceRoot}/shared/b.txt`. Both files lay outside the projects' folders.
1875
+
1876
+ - **Affected.** `nx affected -t build --files=shared/a.txt,shared/b.txt` ran `b:build` only, and `nx affected -t build --files=shared/a.txt` ran no task. The runtime input still keyed the cache: `nx run a:build` was a cache hit twice in a row and a miss after `shared/a.txt` changed.
1877
+ - **Outside the repository.** With a fileset for `{workspaceRoot}/../outside.txt` on `b`, Nx printed no error or warning, and `nx run b:build` was a cache hit after that file changed.
1878
+ - **Ignored files.** With `gen/` in `.gitignore` and a fileset for `{workspaceRoot}/gen/g.txt`, `b:build` was a cache hit after the file changed. With `"includeIgnored": true` on the same fileset, it was a miss after the change and a hit on the next run. Yet `nx affected -t build --files=gen/g.txt` ran no task, and neither did `nx affected -t build --base=HEAD~1 --head=HEAD` after a commit that changed only `gen/g.txt`, added with `git add -f`. A third project `c` with an `includeIgnored` fileset for `nested/sub/h.txt`, a file that `nested/.gitignore` ignored, was selected both with `--files` and after a commit that changed only that file. With `nxig/` in a root `.nxignore`, a project with an `includeIgnored` fileset for `nxig/n.txt` missed the cache after that file changed, and `--files=nxig/n.txt` selected nothing. For `vendor/node_modules/f.txt`, which only Nx's fixed exclusion of `node_modules` folders covers, a project with such a fileset missed the cache after the change and was selected both with `--files` and after a commit that changed the file. As read in the source, Nx drops each changed file that the root `.gitignore` or `.nxignore` matches before it matches changed files against inputs, whatever the filesets say (`calculateFileChanges` in `project-graph/file-utils.js`, with `getIgnoreObject` in `utils/ignore.js`, which reads those two root files only).
1879
+ - **Symbolic links.** In a second, clean repository that ignored `.nx`, project `h` declared `shared/alias.txt`, a symbolic link to `shared/data.txt`, and project `i` declared `shared/data.txt`, both without `includeIgnored`. After `data.txt` changed, `h` was a cache hit with the same `NX_TASK_HASH` as before, and `i` missed with a new one. A commit that changed only `data.txt` selected `i` and not `h`, while `--files=shared/alias.txt` selected `h`. In the first repository, a declared link's hash stayed the same after its destination changed, with and without `includeIgnored` and with the daemon, changed after `nx reset` and after `touch -h` on the link, and then reflected the destination's content: Nx hashes the destination when it first reads the link and keeps that hash until the link itself changes or `nx reset` clears it.
1880
+ - **Paths in `includeIgnored` filesets.** In a third repository, a git repository whose projects each declared one `includeIgnored` fileset in their `default` named input, Nx hashed tasks with and without the daemon. It failed the hash of every task whose fileset had a `.` or `..` segment, such as `{workspaceRoot}/../outside/o.txt` or `{workspaceRoot}/shared/*/../data.txt`, with a message that names the fileset and asks for a path without such a segment. A fileset whose path ran through a symbolic link to a folder, inside or outside the repository, such as `shared/outlink/o.txt` or `shared/outlink/**`, gave a new hash after a file in that folder changed, also when the folder lay outside the repository and the daemon hashed, while `shared/**` did not descend into the linked folders. A fileset that names a folder, `shared/real`, covered its files in the key, and `--files=shared/real/r.txt` selected its project, but not the project whose fileset `shared/inlink/r.txt` ran through `shared/inlink`, a link to `shared/real`. In the review of nxr-d371vy, a commit that only replaced a declared link to a file, `docs/alias.txt`, by one to another file selected no task where the fileset named the link's destination alone: git reports the link's own path as changed. A declared link whose own modification time lay within about a second of a hash was read again at the next hash; the hash stayed the same, as above, once the link was older.
1881
+ - **Failed tasks.** As read in the source, Nx stores a task's result only when the task is cacheable and its exit code is 0, unless `NX_CACHE_FAILURES` is `true` (`shouldCacheTaskResult` in `tasks-runner/task-orchestrator.js`). A fourth project `d` had a cached target whose command appended a line to a log and exited with 1. Run twice without the variable, it executed twice. Run twice with `NX_CACHE_FAILURES=true`, it executed once, and the second run exited with 1 without executing; after a change to an input file, it executed again. A batch executor reports a `TaskResult` per task, with `success` and an optional `status` of `success`, `failure` or `skipped`, and with nothing else that decides whether the result is stored (`config/misc-interfaces.d.ts`).
1882
+ - **Recorded reads.** A target accepts an `ultracache` setting whose modes record the files a task reads and let the recording stand in for the declared inputs (`on`, the default), report undeclared reads (`warn`, and `error`, which behaves as `warn` for now), or record nothing (`off`). The typings call it Nx Cloud only and say that "nothing in the OSS runner records or applies IO" (`UltracacheMode` in `native/index.d.ts`, `ultracache/config.d.ts`).
1883
+
1884
+ The targets of the experiment ran no cargo. The points marked with a source file were read, not run.
1885
+ :::
1886
+
1887
+ :::mara evidence EVD-NX-24-FILESET-SCOPE
1888
+ :mid: 01M7CH4GX6F2REGP5T284NW0DB
1889
+ :title: Which files Nx 24.0.6 matches a fileset with includeIgnored against
1890
+ :status: accepted
1891
+ :supports: ADR-DECLARED-FILE-INPUTS
1892
+ :supports: DES-INPUTS
1893
+ :supports: DES-BUILD-INPUT-CHECK
1894
+
1895
+ A reading of the source of Nx 24.0.6, the tag `24.0.6` of the Nx repository from which the `nx` package installed in this repository was built, and experiments on 14 November 2026 with that package, with Node.js 26.12.0, git 2.56.0 and cargo 1.100.0. The experiments loaded copies of the `declared-files` and `undeclared-files` fixtures through the plugin, without the daemon, and listed the files of a task's key with Nx's `HashPlanInspector` (`hasher/hash-plan-inspector.js`), as the check of [[DES-BUILD-INPUT-CHECK]] does. In `declared-files`, `rust` is the folder of the workspace project `rust`, and `app` and `other` are crates beside `api` that `api` does not depend on.
1896
+
1897
+ - **Source.** The hash planner hashes every fileset with `includeIgnored` among a project's inputs as one group read from the disk (`gather_self_inputs` and `FileSetStore` in `native/tasks/hash_planner.rs`). It splits each brace group whose alternatives are plain names into entries of their own, and reads each entry from its literal prefix, the segments before the first one with glob syntax (`expand_literal_braces` and `partition_glob` in `native/glob/glob_transform.rs`). An entry belongs to the deepest project whose folder is or holds that prefix, the project at the repository root not counted, and it takes only the files whose deepest project is that project, so the files of a project in a folder below are left out, as from a `{projectRoot}` fileset. An entry whose prefix no project's folder holds takes every file it names (`ProjectScope` and `scope_roots` in `native/tasks/hashers/disk_expansion/scope.rs`). `nx affected` matches changed files against such a group with the same rule (`ScopedMatcher`, used in `native/affected/tasks/touched.rs`), and `HashPlanInspector` expands it with the same rule (`native/tasks/hash_plan_inspector.rs`). A fileset under `{workspaceRoot}` without `includeIgnored` is matched against every file that Nx tracks, whatever project holds it (`hash_workspace_files` in `native/tasks/hashers/hash_workspace_files.rs`). A plugin's `createNodes` receives only `nx.json` and the repository root besides its own files, while `createDependencies` receives the merged projects of every plugin (`CreateNodesContext` and `CreateDependenciesContext` in `project-graph/plugins/public-api.d.ts`).
1898
+ - **Glob matching.** Nx builds every glob of a fileset with globset, with `literal_separator`, so that `*` never crosses a `/`, and with backslash escapes, after converting extended groups into globset's syntax: `*(…)` before another segment becomes `*`, `!(…)` there becomes `*` with an exclusion of the group, and `+(…)` reads as one of its alternatives (`build_glob_set` in `native/glob.rs`, `convert_glob` in `native/glob/glob_transform.rs`). A glob that ends in `/` gets `**` after it in Nx's glob of the workspace's files, while the disk expansion of a fileset with `includeIgnored` and `nx affected` first drop the trailing `/` (`normalize_glob`), so that `rust/crates/*/` names only the files directly in `rust/crates` there. The native module exports this engine to JavaScript as `matchGlobPaths` (`native/glob.rs`). Called with a segment followed by one more, it matched `app` and `other` but not `web` for `@(app|other)`, `web` but not `app` for `!(app)`, every name for `*(a|b)`, `a` but neither `ab` nor `web` for `+(a|b)`, `app` and `bpp` for `[ab]pp`, `bpp` but not `app` for `[!a]pp`, no name for `[[:alpha:]]*`, and only `a*b` for `a\*b`.
1899
+ - **Cargo's directories.** On 14 November 2026, in `declared-files` with `rust/target/debug/out.txt` in place, which the fixture's `.gitignore` leaves out of Git, `api` declared `../../**` and then `../../..`, which became the filesets `rust/**` and `**/*` with `includeIgnored`. `HashPlanInspector` listed `rust/target/debug/out.txt` among the files of `api:check` for both, and the key of `api:check` changed after only that file changed: the disk walk of such a fileset enters the folders that Git ignores, and skips only Nx's fixed exclusions such as `node_modules` (`native/walker.rs`).
1900
+ - **Before nxr-1by7h4.** `api` declared one pattern at a time, which became one fileset. `../app/src/main.rs` and `../app/**` reached `rust/crates/app/src/main.rs`. `../*/**`, `../*/**/*`, `../*/src/**`, `../*/src/main.rs`, `../a*/src/main.rs`, `../../*/*/src/main.rs` and `../../../rust/crates/*/src/main.rs`, read from `rust/crates` or `rust`, reached no file of `app` or `other`. `../../../*/crates/*/src/main.rs` and `../../../[r]ust/crates/*/src/main.rs`, read from the repository root, reached `rust/crates/app/src/main.rs`, and `../../../*/banner.txt` reached `docs/banner.txt`, a file of no project. With a `project.json` in `rust/crates/app/web`, `../app/**` left out the file beside it, while `../app/web/**` reached it. `../app/**` reached a file that a `.gitignore` in `rust/crates/app` ignored. In `undeclared-files`, `../**` from `reader` reached no source of a crate that `reader` does not depend on. The patterns that missed the files of other crates thus started inside the folder of the project `rust`; that they reach only files of no project, as nxr-1by7h4 first read them, holds only where `rust` is a project.
1901
+ - **After nxr-1by7h4.** With the filesets that [[DES-INPUTS]] gives the folders of the plugin's projects below where a pattern starts, each of these patterns reached the files that it names in `app` and `other`, and `../**` those of the crates of `undeclared-files`. For each pattern of the declared-files and build input check tests, links, ignored files and a crate without a project among them, the files listed for the tasks of the crates that declare it or depend on it before the change were all listed after it; only the patterns over the folders of crates gained the files of those crates. In the review of the change, `../{app,other}/` left out a member in `rust/crates/other/nested`, and graph creation failed for `../{app,web}/src/**` and `../@(app|other)/src/**` beside a project from a `project.json` in `rust/crates/web`, although Nx hashed the first's files there and the second reaches none. With each alternative of braces read as a pattern of its own and segments matched through `matchGlobPaths`, for 24 patterns with braces, nested ones included, classes, the extended groups above, `**` between segments, folders and the repository root, in a layout with members in `rust/crates/other/nest` and `rust/crates/other/nest/deep` and that project in `rust/crates/web`, every file that Nx's glob finds for the pattern, with `/**` after it where it names folders, was in the key of `api:check`, and graph creation failed exactly for the patterns that reach `rust/crates/web`, and passed with the patterns that the message gives.
1902
+
1903
+ The points marked with a source file were read, not run.
1904
+ :::
1905
+
1906
+ :::mara evidence EVD-NX-24-OPTION-SEMANTICS
1907
+ :mid: 01M7AD4BCYERDMG40D5WH2XMAK
1908
+ :title: What Nx 24.0.6 does with dependency inputs, target merges and its own flags
1909
+ :status: accepted
1910
+ :supports: DES-PLUGIN-OPTIONS
1911
+ :supports: DES-INPUTS
1912
+
1913
+ An experiment and a reading of the `nx` 24.0.6 package installed in this repository, on 13 November 2026, with Node.js 26.12.0.
1914
+
1915
+ The experiment ran in a throwaway Git repository outside this one, with this repository's `node_modules` linked in. Its `nx.json` defined a named input `crate` as `["{projectRoot}/**/*"]`, and it had two projects with `project.json` files. Project `b` redefined `crate` with an `env` entry `B_NAMED` and a `runtime` entry `echo b-named`, and its `test` target had the inputs `crate`, `^crate`, `{ "env": "B_TARGET" }` and `{ "runtime": "echo b-target" }`. Project `a` had an implicit dependency on `b`, a file `a/docs/readme.md`, and a `test` target with the inputs `crate`, `^crate` and `!{projectRoot}/docs/**`. Nx's `HashPlanInspector` (`hasher/hash-plan-inspector.js`) listed the inputs of each task with `NX_DAEMON=false`. Then `nx run a:test --exclude-task-dependencies --output-style=static` ran with `NX_DAEMON=false` and a fresh `NX_CACHE_DIRECTORY`, after each change of a variable or file.
1916
+
1917
+ A second experiment, after the review of the option reference the same day, used rustc 1.100.0 and a throwaway workspace with a stand-in plugin, `stand-in`, that infers for each crate of a Cargo workspace a `test` target running `cargo test` with the input `{projectRoot}/**/*`, and a `probe` target whose executor records the options it receives. A crate's `project.json` laid targets over the inferred ones, which Nx merges with the same function as a plugin's own tables; projects were read back with `nx show project <name> --json`.
1918
+
1919
+ - **Inputs of a dependency.** The plan of `a:test` held `B_NAMED` and `echo b-named` from the named input of `b`, and neither `B_TARGET` nor `echo b-target` from the target of `b`. With `B_NAMED` changed, `a:test` ran again; with only `B_TARGET` changed, it was restored from the cache. The source splits a target's inputs the same way: entries of a named input that a `^` input names are hashed for each dependency, and the target's other entries for the task's own project only (`splitInputsIntoSelfAndDependencies` in `hasher/task-hasher.js`).
1920
+ - **Negated patterns.** `a/docs/readme.md` was not in the plan of `a:test`, and a change to it was a cache hit. A negated pattern in a target's inputs takes out files that another entry of the same list brings in. In the second experiment a test of crate `a` compared `include_str!("../docs/value.txt")` with `1`, and the crate's `project.json` set the `inputs` of `test` to `["...", "!{projectRoot}/docs/**"]`. After `nx run a:test` passed and the file was changed to `2`, `nx run a:test` restored the passing result from the cache, while `cargo test -p a` in the workspace root failed with exit code 101. With `["..."]` alone, the same change made `nx run a:test` run and fail. An excluded file that a macro reads therefore gives a stale result.
1921
+ - **`nx.json`.** `nx.json` was among the files of every task's plan, although no input named it.
1922
+ - **Merging two configurations of one target.** `mergeTargetConfigurations` in `project-graph/utils/project-configuration/target-merging.js`, with `getMergeValueResult` and `mergeArrayValue` in `utils.js` beside it: a field that the later configuration sets replaces the earlier value; `options` and `configurations` are merged key by key; a list without the element `"..."` replaces the earlier list, and `"..."` stands for the earlier entries at its place. When both configurations name an executor and the executors differ, or both run `nx:run-commands` with different commands, the targets are incompatible (`isCompatibleTarget`): the later one is used in place of the earlier one, and the earlier options are discarded. A `command` becomes `nx:run-commands` with that command (`resolveCommandSyntacticSugar`). In the second experiment, a `probe` target in `project.json` with the inferred executor and an option `x` kept the inferred inputs and options and added `x`; with the executor `nx:noop`, or with a `command`, the target had no inputs left and only the options of `project.json`.
1923
+ - **Nx's own flags.** In the second experiment each flag was passed to `nx run b:probe`, `nx run-many -t probe -p b` and `nx affected -t probe --files=<a file of b>`, and the probe recorded whether the option arrived. `--target`, `--configuration`, `--exclude` and `--parallel` never reached the executor, under any of the three commands, and `--runner=zzz` made all three fail. `--projects` reached it under `run` and `affected` but not under `run-many`, which selects projects with it, and `--project` reached it under `run-many` and `affected` but not under `run`, which takes it as the project to run (`command-line/yargs-utils/shared-options.js`). `--profile=release` reached it under all three: Nx switches its own task profiling on with the environment variable `NX_PROFILE` (`tasks-runner/run-command.js`), not with a flag. So did `--features`, `--allFeatures`, `--noDefaultFeatures`, `--targetTriple`, `--allTargets`, `--noDeps`, `--bin` and `--affectedTests`, the option names of [[DES-PLUGIN-OPTIONS]]. An option named `target`, `configuration`, `exclude`, `parallel` or `runner` could not be given on the command line at all.
1924
+ - **`--verbose`.** All three commands consume `--verbose` as Nx's own flag: it is not among a task's overrides. Nx then supplies verbosity to the executor of a single task itself: it adds `verbose: true` to the options when the executor's schema declares a `verbose` property or sets `additionalProperties: true` (`applyVerbosity` in `utils/params.js`). In a third experiment on 13 November 2026, with a stand-in executor recording its options, `nx run`, `nx run-many` and `nx affected` with `--verbose` delivered `"verbose": true` under a schema with `additionalProperties: true` and under one that declares a boolean `verbose`, and no `verbose` under a schema that does neither. A batch implementation with the schema that declares `verbose` and `preferBatch` set received no `verbose` in its tasks' options under any of the three commands. In the same runs `--affectedTests=true` reached the executor under all three commands, as `true` among the options and as `"true"` among the task's overrides in the task graph, in a batch as well.
1925
+ - **`env` of `nx:run-commands`.** That executor's `env` option holds "Environment variables that will be made available to the commands" (`executors/run-commands/schema.json`).
1926
+
1927
+ In the first experiment the projects came from `project.json` files, not from a plugin. That a plugin's named inputs are hashed in the same way is read from the source, where both reach the hasher as project configuration.
1928
+ :::
1929
+
1930
+ :::mara evidence EVD-CARGO-NX-TABLES
1931
+ :mid: 01M7AD4BCY1KGNGB0BSH140SNV
1932
+ :title: How cargo 1.100.0 reports the nx tables of the option reference
1933
+ :status: accepted
1934
+ :supports: DES-PLUGIN-OPTIONS
1935
+ :supports: DES-METADATA-TABLES
1936
+
1937
+ An experiment with cargo 1.100.0 and rustc 1.100.0 on 13 November 2026, with an empty Cargo home and `--offline`, in a throwaway workspace outside this repository. Its root `Cargo.toml` listed the members `crates/*` and excluded `tools/x`, and its `[workspace.metadata.nx]` table set `tags`, `namePrefix`, `envInputs` and a `project` sub-table with `name`. The member `api` set `name` and `implicitDependencies` in `[package.metadata.nx]`, `inputs = ["...", { env = "DATABASE_URL" }, "!{projectRoot}/docs/**"]` in `[package.metadata.nx.targets.test]`, and `affectedTests = false` and `features` among that target's options. The excluded crate `tools/x` had a `[workspace.metadata.nx]` table of its own with `testRunner`.
1938
+
1939
+ - `cargo metadata --format-version 1 --no-deps --offline` in the workspace root reported both tables as written: the `"..."` string, the inline table inside the list and the booleans kept their types and order, under `metadata.nx` of the workspace and of the package. A member without a table had `null` there.
1940
+ - `cargo build --offline` built the workspace without a warning about any of the keys.
1941
+ - In `tools/x`, the report named that folder as the workspace root, with one member and the crate's `[workspace.metadata.nx]` table as the workspace's metadata, and `cargo build --offline` built it. A standalone crate can therefore carry workspace settings in its own manifest.
1942
+ :::
1943
+
1944
+ :::mara evidence EVD-CARGO-LOCKED-CHECK
1945
+ :mid: 01M7AD4BCY0KKX34EHF23320MQ
1946
+ :title: cargo metadata --locked fails on an outdated lockfile without changing it
1947
+ :status: accepted
1948
+ :supports: DES-INVOCATION
1949
+
1950
+ An experiment with cargo 1.100.0 on 13 November 2026, in the workspace of [[EVD-CARGO-NX-TABLES]] with two members and no registry dependencies, an empty Cargo home and `--offline`. After `cargo generate-lockfile`, a path dependency of `api` on `core` was added to `api`'s manifest, so that `Cargo.lock` was out of date.
1951
+
1952
+ - `cargo metadata --format-version 1 --no-deps --locked --offline` succeeded: the report that builds the graph does not notice an outdated lockfile.
1953
+ - `cargo metadata --format-version 1 --locked --offline` exited with code 101 and the message "cannot update the lock file … because --locked was passed to prevent this". `Cargo.lock` was byte for byte unchanged.
1954
+ - After `cargo generate-lockfile`, the same command succeeded.
1955
+
1956
+ `cargo metadata` without `--no-deps` resolves the dependencies, so in a workspace with registry dependencies it needs what the full report needs, the registry or a filled Cargo home ([[EVD-CARGO-NO-DEPS]]). That case was not run here.
1957
+ :::
1958
+
1959
+ :::mara evidence EVD-NX-PLUGIN-ENTRIES
1960
+ :mid: 01M7ABYX5EADNXFRHAA2F17VBK
1961
+ :title: How Nx 24.0.6 runs several entries of one plugin
1962
+ :status: accepted
1963
+ :supports: DES-METADATA-REPORT
1964
+
1965
+ A reading of the `nx` 24.0.6 package and an experiment on 13 November 2026 with cargo 1.100.0 and Node 26.12.0 on Linux. The experiment ran through the plugin's own tests (`nx-rust/test/discovery.spec.ts`), which list a stand-in that behaves as the plugin twice in `nx.json`, with `include` filters that split the manifests between the two entries, and build the graph with plugin isolation on and off.
1966
+
1967
+ - **Isolation on**, Nx's default: Nx starts one plugin worker per entry, keyed by the plugin, the workspace root and the entry's position in `nx.json` (`project-graph/plugins/isolation/load-isolated-plugin.js`). Two entries of one plugin run in two processes and share nothing.
1968
+ - **Isolation off** (`NX_ISOLATE_PLUGINS=false`): Nx loads the plugin module once per process with `require` and gives each entry a shallow copy of its exports (`plugins/load-resolved-plugin.js`), so a module-level variable is shared by all entries. An entry without `options` passes `undefined` to both hooks, so their arguments do not tell entries apart. Nx calls `createDependencies` as a method of the entry's copy and the `createNodes` function as a member of the pair it read from that copy (`plugins/loaded-nx-plugin.js`).
1969
+ - **Order.** Nx starts the `createNodes` calls of all entries of one computation one after another in a single synchronous loop, and calls `createDependencies` once all of them have settled, also when one of them failed (`utils/project-configuration-utils.js`, `project-graph.js`).
1970
+ - **Measured.** With a workspace's root manifest given to one entry and its members to the other, the workspace was reported twice with isolation on, once in each worker. With isolation off it was reported once, when the second entry reused the report that the first had requested in the same computation. The version of the plugin reviewed on 13 November 2026 kept the result of `createNodes` in one module-level variable: with isolation off, both entries' `createDependencies` then received the discovery of the second entry.
1971
+
1972
+ The plugin therefore makes each entry's copy carry a `createNodes` of its own and finds the entry in `createDependencies` through that copy. These are Nx internals, which the tests check in both modes and which have to be checked again for another Nx major.
1973
+ :::
1974
+
1975
+ :::mara evidence EVD-NX-EDGE-CACHE
1976
+ :mid: 01M7AE241Y0VGGYCNWWR01WR7T
1977
+ :title: How Nx 24.0.6 keeps a plugin's edges from one graph to the next
1978
+ :status: accepted
1979
+ :supports: DES-PROJECT-GRAPH
1980
+
1981
+ A reading of the `nx` 24.0.6 package and experiments on 13 November 2026 with cargo 1.100.0 and Node 26.12.0 on Linux: the review of pull request #17 ran the plugin through real Nx with the daemon on and off, and runs through the plugin's test harness (`nx-rust/test/harness`), with the edge type switched by a temporary change, repeated the first case below and tried one alternative. The source files named are in `nx/dist/src`.
1982
+
1983
+ - **Source files.** An edge of the type `static` or `dynamic` names a source file, which Nx accepts when it is a file of the source project or one of the files that belong to no project: the review saw `nx.json` accepted, and another project's manifest and a file that does not exist rejected (`getFileData` in `project-graph/project-graph-builder.js`). Nx records such an edge in the data of that file, and then builds the `static` and `dynamic` edges of each project from its files' records. An `implicit` edge names no file and is kept as the plugin returned it (`getUpdatedProjectGraph` and `calculateAlreadySetTargetDeps` there). `dynamic` behaves as `static` throughout.
1984
+ - **Reuse.** Nx caches the records by project name, file path and file hash. After the plugins' `createDependencies`, it puts the cached records of each file whose project, path and hash are unchanged in place of the records just made for it, and it does so only where the cache holds records for that file (`extractCachedFileData` and `processProjectNode` in `project-graph/nx-deps-cache.js`, `buildProjectGraphUsingContext` in `project-graph/build-project-graph.js`).
1985
+ - **Invalidation.** Nx discards the whole cache when its format or the Nx version changed, when a project name of the previous graph is gone, when an existing TypeScript path mapping changed, when the name, version or `options` of a plugin entry changed, when `pluginsConfig` changed, or when the hash of the external nodes changed (`shouldRecomputeWholeGraph` in `project-graph/nx-deps-cache.js`). A new project does not discard it, and neither does a change to a plugin entry's `include` or `exclude`, which the comparison leaves out (`getNxJsonPluginsData`).
1986
+ - **Measured.** The review created the graph of a fixture twice, with one change between the two, once with the plugin's edges returned as `static`, once as `dynamic`, each naming the manifest of its source project, and once as `implicit`, with the Nx daemon on and off. The outcomes were the same with and without the daemon. "Wrong" means an edge that was missing or still pointed at the old target:
1987
+
1988
+ | Change between the two graphs | `static` or `dynamic` | `implicit` |
1989
+ | ---------------------------------------------------- | --------------------- | ---------- |
1990
+ | A crate removed from `.nxignore` | wrong | right |
1991
+ | A crate removed from `.gitignore` | wrong | right |
1992
+ | The plugin entry's `exclude` removed | wrong | right |
1993
+ | The plugin entry's `include` widened | wrong | right |
1994
+ | A new member under an unchanged `members` glob | wrong | right |
1995
+ | A `[workspace.dependencies]` entry retargeted | wrong | right |
1996
+ | A project renamed through `project.json` | right | right |
1997
+ | Only the version requirement of a dependency changed | right | right |
1998
+
1999
+ The runs through the harness repeated the first row without the daemon in `subfolder-workspace`: with `static` and with `dynamic` edges, the second graph had no edge from `api` or `rust` to `testkit`, although `createDependencies` returned both, and with `implicit` edges both were there. The test "adds an edge when a crate gets a project and no manifest changes" in `nx-rust/test/graph.spec.ts` keeps this case.
2000
+
2001
+ - **Alternatives.** Another source file, such as the workspace's root manifest or its lockfile, fails in the same way, because the edges still depend on other files. A file that belongs to no project, such as `nx.json`, is reused by its hash in the same way, and Nx keeps only one edge per target and type in such a file's records: in a run through the harness with `nx.json` as the source file of every edge, the first graph of `subfolder-workspace` already lacked the edges from `rust` to `codegen` and to `model`, two crates that `api` depends on as well. `NX_DAEMON=false NX_CACHE_PROJECT_GRAPH=false` turns the reuse off, but for every plugin and the whole graph, each user has to set both on every command, and the second variable has no effect while the daemon runs (`project-graph/project-graph.js`). Nx 24.0.6 offers a plugin no way to discard its own part of the cache.
2002
+ - **Other readers of the type.** Nx's task graph, `affected` and the task hasher follow edges of every type. In the rest of the `nx` package, leaving out the graph viewer and the JS plugin, which were not read, only Nx release tells the types apart: the default `readDependencies` of its `VersionActions` leaves out `implicit` edges, and an implementation can override it (`command-line/release/version/version-actions.js`). In `@nx/eslint-plugin` 24.0.6, read and not run, the rule `enforce-module-boundaries` follows edges of every type when it looks for circular dependencies, for projects reachable under tag constraints and for transitive external dependencies (`buildMatrix` in `dist/src/utils/graph-utils.js`). It reads the type only to find lazy-loaded imports, from `dynamic` edges (`hasDynamicImport` in `dist/src/utils/runtime-lint-utils.js`), and it names the files along a circular path from the files' records, which hold nothing for an `implicit` edge (`findFilesInCircularPath`).
2003
+
2004
+ A crate's edges depend on more than its own manifest: on the `[workspace.dependencies]` of its workspace's root manifest, on the ignore files and the plugin entry's options, which decide which crates are projects, and on the members that a glob matches. The plugin therefore returns its edges as `implicit`, and Nx recomputes them on every graph computation. These are Nx internals, to be checked again for another Nx major.
2005
+ :::
2006
+
2007
+ :::mara evidence EVD-NEXTEST-CARGO-FLAGS
2008
+ :mid: 01M7AH88BCFA99QFV4EGE16JHW
2009
+ :title: cargo-nextest takes the Cargo profile as --cargo-profile
2010
+ :status: accepted
2011
+ :supports: DES-PLUGIN-OPTIONS
2012
+
2013
+ An experiment on 13 November 2026 with cargo-nextest 0.9.151, the prebuilt binary from `https://get.nexte.st/latest/linux`, and cargo and rustc 1.100.0, in a throwaway crate with a unit test, a doctest, a feature `extra` and a Cargo profile `custom` that inherits from `dev`. No `.config/nextest.toml` existed.
2014
+
2015
+ - `cargo nextest run --profile custom` failed with exit code 96 and "profile `custom` not found (known profiles: default, default-miri)": nextest reads `--profile` as a profile of its own configuration.
2016
+ - `cargo nextest run --cargo-profile custom` built with Cargo's profile `custom`, into `target/custom`, and ran the test under nextest's profile `default`.
2017
+ - `cargo test --doc --profile custom` built with the profile `custom` and ran the doctest.
2018
+ - `cargo nextest run` accepted `--features`, `--all-features`, `--no-default-features` and `--target` as cargo does; its help lists them beside `--cargo-profile`.
2019
+ :::
2020
+
2021
+ :::mara evidence EVD-CARGO-TEST-TARGET-SELECTOR
2022
+ :mid: 01M81Q6JXEKKG19E0HAXAW0Q6W
2023
+ :title: What cargo and nextest do with --test <name>
2024
+ :status: accepted
2025
+ :supports: DES-TEST-RUN
2026
+ :supports: DES-BATCH
2027
+ :supports: DES-PLUGIN-OPTIONS
2028
+
2029
+ Experiments on 22 November 2026 with cargo 1.100.0 (3acc79c0c 2026-11-05) and cargo 1.91.0 (ea2d97820 2025-10-10), each with its rustc, and cargo-nextest 0.9.152, in a throwaway virtual workspace outside this repository, for nxr-k5y74e. Its members were `a`, a library with a unit test and a doctest, a binary `a` with a test of its own and the integration tests `performance`, which asserts that `CARGO_BIN_EXE_a` exists, and `other`; `b`, a library with a unit test and a doctest and the integration tests `bonly` and `performance`; and `c`, a library without tests. No `.config/nextest.toml` existed. Both versions gave the same results, apart from the case of one word in an error message.
2030
+
2031
+ - **One crate.** `cargo test -p a --test performance` built the library and the binary `a` in normal mode and the test executable `performance`, as its JSON messages with `--no-run` showed, and ran `performance` alone: no unit test, no test of the binary, no other integration test and no doctest. With `--profile release` it built with that profile and ran the same test.
2032
+ - **Unknown names.** `cargo test -p a --test nosuch` failed with exit code 101 and ``no test target named `nosuch` in `a` package``, and the empty name failed the same way, with the list of the package's test targets. A glob pattern selected what it matched: `--test 'perf*'` ran `performance`, and `--test 'zz*'` failed with 101 and ``no test target matches pattern `zz*` in `a` package``.
2033
+ - **Several crates.** `cargo test -p a -p c --test performance` ran `a`'s `performance` and exited with 0, although `c` has no such target, and `cargo test -p a -p b --test bonly` ran `b`'s `bonly` and exited with 0; with `-p a -p b --test performance` it ran the target of both. Under `--workspace`, `--test bonly` ran `b`'s target and exited with 0, and a name that no member has failed with 101 and ``no test target named `nosuch` in default-run packages``. Cargo fails only where no selected package has the target, so whether a crate's selection fails depends on what else the command selects.
2034
+ - **Doctests.** `cargo test -p a --test performance --doc` failed with 101 and `can't mix --doc with other target selecting options`, while `cargo test -p a --doc` ran the doctest.
2035
+ - **nextest.** `cargo nextest run -p a --test performance --no-tests=pass` passed `--test=performance` to the `cargo test --no-run` that it builds with and ran the one test of that binary, also with `--cargo-profile release`. An unknown name, the empty one included, failed with 101 and cargo's error. With `-p a -p c` it ran `a`'s test and exited with 0, and with `--workspace --test bonly` it ran `b`'s, as cargo does. `cargo nextest run` rejected `--doc` as an unexpected argument; nextest runs no doctests.
2036
+ - **A target with `test = false`.** In this repository's `binary-tests` fixture, whose crate `untested` has a binary that prints `plain`, or `extra` with the feature that its dev-dependency turns on, and one `[[test]]` named `skipped` with `test = false`: after `cargo build -p untested`, a plain `cargo test -p untested` left `target/debug/untested` as it was, the same inode, while `cargo test -p untested --test skipped` built and ran `skipped` and replaced the executable with one that prints `extra`, on both versions.
2037
+ :::
2038
+
2039
+ :::mara evidence EVD-TEST-MODE-READING
2040
+ :mid: 01M7JW7PCJ272NSR2P2F6GTVJ4
2041
+ :title: How the mode command can read cargo-affected's database without writing beside it
2042
+ :status: accepted
2043
+ :supports: DES-TEST-MODE
2044
+
2045
+ Experiments on 16 November 2026 on Linux x86-64 with Node 26.12.0 and its `node:sqlite`, in throwaway folders, and a reading of cargo-affected 0.4.1's `src/db.rs`, the version of [[EVD-CARGO-AFFECTED-REPORT]].
2046
+
2047
+ - **The schema.** cargo-affected opens `target/affected/coverage.db` in WAL mode with `synchronous=NORMAL` and keeps one row per test and covered range in `test_regions`, whose column `collect_sha` names the commit of the collection, beside `env_fingerprint`; it reads a fingerprint's commits with `SELECT DISTINCT collect_sha FROM test_regions WHERE env_fingerprint = ?1` and keeps the rows of up to ten earlier fingerprints. An older schema without these columns is dropped when cargo-affected opens the database.
2048
+ - **A read-only connection writes beside the database.** A database in WAL mode that its writer had closed, so that only `coverage.db` was left, opened with `readOnly: true` and read, left `coverage.db-shm` of 32 KiB and an empty `coverage.db-wal` behind after the connection closed. Opened through a `file:` URL with `immutable=1` and `readOnly: true`, the same database was read and no file was created; the database's modification time and bytes stayed the same.
2049
+ - **A `-wal` file and the reader.** An immutable connection ignores the `-wal` file and takes no lock, so with a writer's connection open and automatic checkpoints off, the rows that lay only in the `-wal` file are not in what it reads. An ordinary read-only connection reads them, but where the writer closed between a look for the `-wal` file and the open, as a collection ending does, it found the database closed and created new `-wal` and `-shm` files, and a database restored with its `-wal` file but without `-shm` got a `-shm` file the same way (the review of nxr-539qtw). With the plugin's tests, which put a step between the look and the open: a database restored with its `-wal` file, with or without `-shm`, a collection that opens the database in between, one that is open at the first look and closes afterwards, and a database replaced in between each gave no commits and left every file as it was, and a closed database gave its commits and left nothing behind.
2050
+ - **Cost.** `SELECT DISTINCT collect_sha FROM test_regions` on a database of cargo-affected's schema and index with 700,000 rows, 203 MB, three commits and two fingerprints took 39 to 46 ms, opening and closing included, with the file in the page cache. A start of Node that loads `node:sqlite` took 15 to 19 ms, as one without it.
2051
+
2052
+ So the command reads the commits only through an immutable, read-only connection, which writes nothing, and only where no `-wal` file lies beside the database before and after the read and the database file stayed the same; otherwise the mode is `full`. A database that cargo-affected 0.4.1 itself wrote gave its commit in nxr-tabkjx, and no file beside it changed ([[EVD-AFFECTED-RUNS]]). Not run: a cold page cache, macOS, and Node 22, whose `node:sqlite` needs 22.13 or later without a flag.
2053
+ :::
2054
+
2055
+ :::mara evidence EVD-NEXTEST-RUNNER-STEPS
2056
+ :mid: 01M7JJZMG61K9MHV5XRK94E3Y1
2057
+ :title: What the nextest runner's steps rest on: exit statuses, the JUnit report and plain commands
2058
+ :status: accepted
2059
+ :supports: DES-TEST-RUN
2060
+ :supports: DES-TEST-PHASES
2061
+
2062
+ Experiments on 16 November 2026 on Linux x86-64 with cargo-nextest 0.9.152 (26ebeda79 2026-11-13), installed with `cargo install --locked` into a folder of its own, and cargo and rustc 1.100.0, in a throwaway workspace with the members `a`, a library with a passing and a failing unit test and a doctest, `b`, with a passing unit test, and `e`, a library without tests; then the tests of nxr-jb6g5y in `nx-rust/test/nextest-runs.spec.ts` on the `workspace-tests` fixture with cargo 1.100.0 and 1.91.0.
2063
+
2064
+ - **The report.** With a tool configuration that set only `path` under `[profile.default.junit]` to an absolute path, `cargo nextest run --workspace --no-fail-fast --no-tests=pass --tool-config-file nx-rust:<file> -E 'package(=a) | package(=e)'` exited with 100 and wrote one `testsuite` per binary that ran, named by its binary ID, with a `testcase` per test, `failure` in the failed one, and the test's output in `system-out` and `system-err` with `<`, `>` and `'` escaped, so that output that holds `</testcase><failure>` stays text. Where `.config/nextest.toml` set `path = "repo.xml"` under `[profile.default.junit]`, nextest wrote `target/nextest/default/repo.xml` and nothing to the tool configuration's path.
2065
+ - **The statuses.** A member that did not compile made nextest exit with 101, after cargo's `error: could not compile` lines for it, which name the crate as under `cargo test`. `cargo nextest run -p e` on a member without tests exited with 4 and "no tests to run"; with `--no-tests=pass` it exited with 0. `cargo nextest run --help` lists `--no-run`, `--locked`, `--cargo-profile`, `--no-tests` and `--archive-file`.
2066
+ - **Its lines.** Without a terminal, nextest wrote no progress bar. Each test's line named its binary ID after the status, the time and a counter, such as `FAIL [ 0.002s] (1/2) a t::bad`, with the test's output indented under it; with `CARGO_TERM_COLOR=always` the same lines held colour sequences around the status and around each part of the name. The `Starting` line of a run whose default filter left out a test read `Starting 4 tests across 4 binaries (1 test and 7 binaries skipped, including 1 test via profile.default.default-filter)`.
2067
+ - **Doctests of one crate.** `cargo test -p e --doc` passed for a library with `doctest = false`, as for one without doctests.
2068
+
2069
+ Further experiments and reading of nextest's source the same day (cargo-nextest 0.9.152, nextest-runner 0.130.0, nextest-metadata 0.15.0), after a review of nxr-jb6g5y:
2070
+
2071
+ - **Runs that end early.** In a workspace with one test thread, `a`'s tests first through `priority`, `a`'s test sleeping three seconds and `b` with one failing and one passing test, `global-timeout = "1s"` made nextest kill `a`'s test, print `1/2 tests were not run due to global timeout` and exit with 100; the report held `a`'s killed test as failed and nothing of `b`. A SIGTERM and a SIGINT sent to nextest during `a`'s test did the same, with `2/3 tests were not run due to signal` and `due to interrupt`. In the source, nextest's final state is a success only where every test that the run was to run finished and none failed (`RunStats::summarize_final`), and a run cancelled during the tests ends with 100 like one in which a test failed (`final_result`), so that exit status 0 shows a complete run and 100 does not tell the two apart. The report only holds tests that ran, and a test that a filter left out appears, as a `testcase` with a `skipped` element, only where `junit.report-skipped` asks for it.
2072
+ - **fail-fast.** `--no-fail-fast` on the command line sets the run's `max-fail`, and the profile's `fail-fast` or `max-fail` applies only where the command line sets none; no variable sets it (`dispatch/core/run.rs`, `TestRunnerBuilder::build`). The tests of nxr-jb6g5y showed `b`'s tests running after `a`'s failure with `fail-fast = true` and with `max-fail = 1`.
2073
+ - **The list.** `cargo nextest list --message-format json -E 'package(=a) | package(=b)'` printed `rust-suites` by binary ID, each with `package-name`, `package-id` and `testcases`, each test with `filter-match` `{"status":"matches"}` or `{"status":"mismatch","reason":…}`, such as `ignored` for an ignored test and `default-filter` for one that the repository's default filter left out. nextest documents this output as stable.
2074
+ - **Setup scripts.** With `experimental = ["setup-scripts"]` and a script for `all()`, the report held a suite `@setup-script:prepare` with one passing `testcase` beside the test binaries' suites, and nextest exited with 0. A script that failed made nextest cancel the run with `Cancelling due to setup script failure`, run no test and exit with 105, the report holding the script's suite with a `failure` element. The report names suites by binary ID or as `@setup-script:<id>`, either with `@stress-<n>` after it in a stress run (`SuiteKey` in `reporter/aggregator/junit.rs`).
2075
+ - **Its version.** `cargo nextest --version` in the workspace root printed nextest's version, commit and host, and found a stand-in for `cargo-nextest` on `PATH` as cargo finds the subcommand for a run.
2076
+
2077
+ So the plugin can decide each task from the status and the report alone, a failed build reads as for `cargo test`, and a group of one crate needs `--no-tests=pass` for a crate without tests to pass as it does under `cargo test`. After 100, only nextest's list shows which tests of a crate were to run, and a crate passes only where all of them ran and passed.
2078
+ :::
2079
+
2080
+ :::mara evidence EVD-NX-24-ENTRY-CONTEXT
2081
+ :mid: 01M7AH88BCK4ZK4JY2X0N7C9C0
2082
+ :title: What each entry of a plugin sees of the others in Nx 24.0.6
2083
+ :status: accepted
2084
+ :supports: DES-PLUGIN-OPTIONS
2085
+
2086
+ An experiment on 13 November 2026 with `nx` 24.0.6 and Node.js 26.12.0, in a throwaway Git repository outside this one. A Cargo workspace in `rust/` had the members `a`, `b` and `hidden`, and `.nxignore` named `rust/crates/hidden`. `nx.json` listed a stand-in plugin twice: one entry with `include` set to `rust/Cargo.toml` and `rust/crates/a/**` and the option `testRunner` set to `cargo`, the other with `include` set to `rust/crates/b/**` and `rust/crates/hidden/**` and `testRunner` set to `nextest`. The stand-in's `createNodes` for `**/Cargo.toml` recorded the files it received, the `plugins` of `context.nxJsonConfiguration`, and, for every entry naming the stand-in, the result of `findMatchingConfigFiles` applied with that entry's `include` and `exclude` to the output of `globWithWorkspaceContext(workspaceRoot, ["**/Cargo.toml"])`. `nx show projects` ran with plugin isolation on (the default), with `NX_ISOLATE_PLUGINS=false`, and with the Nx daemon on.
2087
+
2088
+ - **Every entry sees all.** In every mode both entries' contexts held both entries of `plugins`, with their `include` patterns and options. With isolation on, and with the daemon, the two entries ran in two processes; with isolation off, in one.
2089
+ - **Nx's assignment can be recomputed.** For each entry, applying its own `include` and `exclude` to the files of the workspace context gave exactly the files that Nx handed to it, also leaving out the manifest under the `.nxignore` path that the second entry's `include` matched. So each entry can tell which entries receive manifests of a workspace, and with which options. Every `include` of this experiment held `**`; for a narrow one, Nx takes a step before (**The whole pipeline**).
2090
+ - **The whole pipeline.** The review of nxr-v1b7rc on 15 November 2026 found, and a reading of the installed `nx` 24.0.6 (`dist/src`) confirmed, that Nx chooses an entry's files in two steps. `retrieveProjectConfigurations` (`project-graph/utils/retrieve-workspace-files.js`, lines 46–60), which graph creation calls without the daemon (`project-graph/project-graph.js`, line 104) and in it (`daemon/server/project-graph-incremental-recomputation.js`, line 459), takes each entry's files from `globPluginFiles` (lines 111–122). For an entry whose `include` is not empty and has no pattern with `**`, `!`, `(` or `)` (`canGlobInclude`, lines 125–128), that globs the `include` patterns natively in the workspace context and keeps the files that the entry's `createNodes` pattern matches by minimatch with `dot: true`; for every other entry, a plain string included, it globs the `createNodes` pattern natively. Then `createProjectConfigurationsWithPlugins` (`project-graph/utils/project-configuration-utils.js`, line 37) applies `findMatchingConfigFiles(files, include, exclude)` (line 63; lines 287–325, minimatch with `dot: true`) and hands the result to the entry's `createNodes`. The `include` and `exclude` are those of the entry in `nx.json` as written (`project-graph/plugins/loaded-nx-plugin.js`, lines 18–22; in a plugin worker, `project-graph/plugins/isolation/isolated-plugin.js`, line 229).
2091
+ - **The native glob differs.** Measured the same day with a stand-in that recorded, for every entry, the files Nx handed it and two recomputations, in a copy of the fixture `shared-executables` (a workspace in `rust/` with three members, a standalone crate in `tools/`, and a crate in `.hidden/` added), with plugin isolation on and off and with the Nx daemon. The `include` patterns `rust/[[:upper:]]argo.toml`, `rust//Cargo.toml` and `rust/../rust/Cargo.toml` match `rust/Cargo.toml` by minimatch but not natively, so Nx handed that manifest to no entry with such an `include`, while `findMatchingConfigFiles` applied to every `Cargo.toml` of the workspace context gave it to the entry. For every other `include` measured, `rust/crates/*/Cargo.toml`, `rust/{Cargo,Other}.toml`, `rust/Cargo.tom?`, `.hidden/Cargo.toml`, patterns with `**` and none, both gave the same files. That recomputation gave a superset of Nx's files in every case, never fewer: Nx's narrow step only removes files before the step that both share, as long as the native glob of `**/Cargo.toml` holds every file that its minimatch matches, which it did for the root manifest, nested manifests and the one in a dot folder.
2092
+ - **The pipeline can be called.** `retrieveProjectConfigurationPaths` (lines 72–75) runs `globPluginFiles` for the entries it is given and flattens the result, and the module resolves as `nx/src/project-graph/utils/retrieve-workspace-files` through the `./src/*` export of the `nx` package. Called with one entry, as `{ createNodes: [pattern], include, exclude }`, and followed by `findMatchingConfigFiles`, it gave exactly the files that Nx handed that entry in every case above, in every mode, and through the daemon also for a manifest added after the daemon had created the graph once.
2093
+ - **Source.** Nx passes the whole `nx.json` as `nxJsonConfiguration` to each entry's `createNodes`. `findMatchingConfigFiles` and `globWithWorkspaceContext` are exported from `nx/src/devkit-internals` only, and `retrieveProjectConfigurationPaths` from its own module; these are interfaces that can change between majors ([[RISK-UPSTREAM-CHANGES]]).
2094
+
2095
+ The stand-in was not the plugin; how the plugin's two entries share reports is [[EVD-NX-PLUGIN-ENTRIES]].
2096
+ :::
2097
+
2098
+ :::mara evidence EVD-CARGO-REDIRECTIONS
2099
+ :mid: 01M7AQ4FBNBJZK6DKFSMS2793S
2100
+ :title: What cargo does with [patch], [replace] and paths, and what the plugin can see of them
2101
+ :status: accepted
2102
+ :supports: ADR-REDIRECTION-EDGES
2103
+ :supports: ADR-SKIP-VENDORED-CRATES
2104
+
2105
+ Experiments on 13 November 2026 with cargo 1.100.0, the main cases repeated with 1.91.0, on Linux, and a reading of the `nx` 24.0.6 package. Each experiment ran in a throwaway repository with a `CARGO_HOME` of its own, in which `[source.crates-io] replace-with` replaced crates.io by a local registry, a `file://` git index holding `model 0.1.0` and `wrapper 0.1.0`, which depends on `model ^0.1`. The workspace had the members `api`, with `model = "0.1"`, `viaw`, with `wrapper = "0.1"`, and `model 0.1.5`. The commands were `cargo metadata --format-version 1 --no-deps --offline`, `cargo metadata --format-version 1 --offline` with and without `--locked`, `cargo tree --offline -e normal,build,dev` and `cargo generate-lockfile`, and `Cargo.lock` was read after each. Both versions gave the same results except for `include`.
2106
+
2107
+ - **The graph's report shows nothing.** With `[patch.crates-io] model = { path = "crates/model" }` in the root manifest, the `--no-deps` report listed `api`'s dependency with the crates.io source and no `path`, and was identical to the report without the patch. So it was for every way of redirecting below, and with a patch path that does not exist the report still succeeded. The full report and `cargo tree` named the local crate, and `Cargo.lock` held it as an entry without `source` and without its folder.
2108
+ - **Where cargo reads them.** From the workspace's root manifest, `[patch]` entries with a `path`, for crates.io, for a registry named in `[registries]` and for a git URL, and `[replace]` entries with a `path`; cargo rejects a manifest that has both tables. A `[patch]` in a member's manifest is ignored, with the warning "patch for the non root package will be ignored", which `--no-deps` prints too. From `.cargo/config.toml`, and the older `.cargo/config`, in the folder cargo starts in and in each folder above it, from `config.toml` in the Cargo home, and from `--config`: `[patch]` entries and `paths`. A relative path in such a file resolves against the folder above the one that holds the file: the folder that holds `.cargo`, the one that holds the Cargo home, and for a file that `include` names, the folder above that file's folder. Cargo 1.100.0 applied a `[patch]` from an included file, in the plain and in the `{ path = … }` form; 1.91.0 ignored it. Started outside the workspace with `--manifest-path`, cargo did not read the workspace's `.cargo/config.toml`. `CARGO_PATCH_CRATES_IO_MODEL_PATH` had no effect. A `[patch]` or `[replace]` path has to be the crate's own folder, while `paths = ["local"]` took `model` from `local/inner/model`.
2109
+ - **Who uses the crate.** `viaw` was built with the local `model` through `wrapper` alone, which `--no-deps` shows only as `viaw → wrapper`. A crate `m` whose workspace has the patch and that depends by path on `l`, a member of another workspace that declares `model = "0.1"`, was built with the local `model` through `l`; `l` built in its own workspace got the registry's. A redirection applies to everything cargo builds for the workspace that has it.
2110
+ - **Whether it is used.** A patch whose version does not satisfy the requirement, 0.2.0 for `^0.1`, and a patch to 0.1.5 added after `Cargo.lock` had locked the registry's 0.1.0, were not used until `cargo update`: without a message where the patched crate is a member, otherwise with "patch … was not used in the crate graph" and a `[[patch.unused]]` entry in the lockfile. A patch of the locked version was used at once. `paths` put the local 0.1.5 in place of the locked 0.1.0 and left no trace in `Cargo.lock`; `[replace]` added `replace = "model 0.1.0"` to the registry's entry.
2111
+ - **What resolving costs.** The full report and `cargo tree` failed offline until every package had been downloaded ("failed to download `wrapper`"), and for a git dependency until the git source had been fetched, although it was patched. Without `--locked` they created a missing `Cargo.lock` and rewrote a stale one, also when they failed afterwards; with `--locked` they failed on either.
2112
+ - **Configuration files and `include`.** With both `.cargo/config` and `.cargo/config.toml` in one folder, Cargo 1.91.0 and 1.100.0 read only `config`, with the warning "both … exist. Using … config", and an unparsable `config.toml` beside it stopped neither. An `include` of an unparsable file stopped `cargo metadata --no-deps` with 1.100.0 and not with 1.91.0, which ignores `include`.
2113
+ - **A crate that cargo builds but does not report.** In a workspace with `members = ["api"]` whose root manifest patches `model` to `local`, a folder inside the workspace's folder holding `model` without `[workspace]`, `cargo check` succeeded, while `cargo metadata --no-deps --manifest-path local/Cargo.toml` and `cargo read-manifest` failed on both versions with "current package believes it's in a workspace when it's not"; `cargo locate-project` succeeded but names only the manifest.
2114
+ - **Version requirements.** For 43 pairs of a requirement and a local version, of every form the plugin evaluates (bare, `^`, `~`, `=`, `>`, `>=`, `<`, `<=`, comma-joined, `*`, `1.*`, `1.2.*`, and a version with build metadata), a dependency patched to the local crate resolved with an empty Cargo home and offline exactly when the version satisfied the requirement, on both versions (`nx-rust/test/version-req.spec.ts`).
2115
+ - **Vendoring.** After `cargo vendor` into the workspace with `[source]` replacement, every report showed the registry as the source, cargo refused to build an edited vendored file because its checksum changed, and `cargo metadata --no-deps` in a vendored crate's folder failed with "current package believes it's in a workspace when it's not".
2116
+ - **Vendoring, both placements.** Repeated on 13 November 2026 with cargo 1.100.0 and 1.91.0 and `nx` 24.0.6, from a registry outside the repository whose index is a `file://` git repository, holding `hello 0.1.0`, which depends on `greet 0.1.0`, with a member depending on `hello = "0.1"` and, in one run, also on `remote` from a `file://` git repository. `cargo vendor` ignores `[source]` configuration unless `--respect-source-config` is given, and 1.91.0 failed for a `local-registry` source, looking for the crate files in the Cargo home's cache. It wrote every crate, from the registry and from git, with `.cargo-checksum.json` beside a `Cargo.toml` without `[workspace]`, and printed the `[source]` tables to add, for the git source a table of its own. With those tables in the workspace's `.cargo/config.toml` and an empty Cargo home, `cargo build --offline --locked` built the workspace from the vendored sources, also with `directory = "../vendor"`, which resolved against the folder that holds `.cargo`. Without the tables it failed, looking for `hello` in the crates.io index; with `vendor/greet/.cargo-checksum.json` removed it failed, because cargo could not read that file. Into `vendor` inside the workspace's folder, `cargo metadata --no-deps` failed as above in a vendored crate's folder and from the workspace root with `--manifest-path`; into `../vendor`, outside every workspace's folder, it reported each crate as a workspace of its own. Through the plugin before nxr-9ezy43, the first placement failed graph creation with cargo's message and the second gave `greet` and `hello` projects. A member's `greet = { path = "../../vendor/greet" }` made cargo list `greet` among the workspace's members; with `exclude = ["vendor"]` it was no member, the build still succeeded, and `cargo metadata --no-deps --manifest-path vendor/greet/Cargo.toml` succeeded.
2117
+ - **A `[source]` directory over crates of the repository.** In the review of a first version of nxr-9ezy43 on the same day, which skipped the manifests in every folder that a `[source]` table's `directory` names, `[source.review]` with `directory = "../shared"` in `backend/.cargo/config.toml`, in a repository where `server` in the `backend/` workspace depends by path on `model`, a member of the `shared/` workspace, removed the projects `model` and `shared` and the edge from `server` to `model`. So did the folder named through a symbolic link and from the Cargo home's configuration, and `directory = "."` at a repository root removed the projects of its `tools/` workspace. With that table, `cargo build --offline --locked` in `backend/` still compiled `model` from `shared/crates/model`, on both versions.
2118
+ - **The crates below a `paths` folder.** Experiments on 14 November 2026 with cargo 1.100.0 and 1.91.0, in a throwaway workspace with a `CARGO_HOME` of its own, whose member depended on `model` from a `file://` git repository, with `paths = ["../local"]` in the workspace's `.cargo/config.toml`. In each run a copy of `model 0.1.0` lay elsewhere below `local`, and the full `cargo metadata --offline` showed which manifest cargo took. Both versions gave the same results, which agree with `read_packages` and `walk` in `src/cargo/sources/path.rs` of cargo 0.92.0, the cargo of Rust 1.91. Cargo walks the folder to any depth, six levels in the experiment, and takes every folder that holds `Cargo.toml`: also below a folder whose manifest is a package or a virtual workspace, a folder with `.cargo-checksum.json`, one in `node_modules` and one in a folder holding `CACHEDIR.TAG`. Below the folder itself it skips every folder whose name starts with `.` and every folder that holds `.git`, a folder or a file, and at every level a folder named `target` beside a `Cargo.toml`; it also skipped `target` beside an empty `Cargo.toml`, and went into it beside a dangling link of that name. It followed a symbolic link given as the folder and no link below it, and skipped a folder it could not read. A manifest that it could not parse stopped nothing where another crate was found; with no crate at all, also with none but such a manifest, cargo failed with "failed to update path override". Of two crates with one name, it took the first in its walk, which sorts each folder's entries by name and visits a folder before what lies in it, with the warning "skipping duplicate package". Cargo also took, from each crate it found, its path dependencies wherever they lay, of every kind and to any depth, as `read_nested_packages` reads them: a normal dependency, a dev-dependency, a build-dependency and a dependency for another platform of a crate `seed` below the folder each made cargo take `model` from a folder outside it, and so did a dev-dependency of a dev-dependency outside the folder; cargo compiled `model` into the member and neither `seed` nor the crate between. Both versions wrote a `CACHEDIR.TAG` into the artifact directory and into the build directory, with the line "# This file is a cache directory tag created by cargo." after the signature. The plugin's walk over a folder with 440 folders below it, 40 of them crates, took 2 to 5 ms on this machine, and one `cargo metadata --no-deps` for a crate about 6 to 9 ms. Over a folder holding a `node_modules` folder, a hard-linked copy of this repository's pnpm store with 6,367 folders that the walk enters, and the artifact directory of a workspace of 250 crates with build scripts after `cargo build` and `cargo check`, 5,005 folders, the walk took 89 to 122 ms, the first call in a fresh process included; neither held a `Cargo.toml`, so it cost no cargo call.
2119
+ - **Nx.** In `nx` 24.0.6, the daemon subscribes to changes below the repository root (`subscribeToWorkspaceChanges` in `daemon/server/server.js`) and runs every plugin's `createNodes` again after any such change (`processFilesAndCreateAndSerializeProjectGraph` in `daemon/server/project-graph-incremental-recomputation.js`); without the daemon, every command does (`project-graph/project-graph.js`). A change to a file outside the repository reaches a daemon's graph only with the next change inside it. The changes come from the workspace's file map, which holds the files that the watch tracks "with the ignore rules applied" (`trackedFilesInContext` in `utils/workspace-context.js`).
2120
+ - **Ignored configuration files.** Experiments on 14 November 2026 with `nx` 24.0.6, cargo 1.100.0 and the real Nx daemon, in copies of the fixture `patched-workspaces` without the root manifest's `[patch]` of `model`, holding a `rust/.cargo/config.toml` with a comment only. With `rust/.cargo/` in `.gitignore`, and in another copy in `.nxignore`, after `nx show projects --affected --files=rust/crates/model/src/lib.rs` had listed `model` and `rust`, a `[patch]` of `model` written into that file left the same list three seconds later; once a member's source changed, the list held `api`, `viaw` and the other members that may use `model`. Without the ignore rule, the list held them right after the change to the configuration file. Nx's task hasher left an ignored configuration file out of the key: `HashPlanInspector` listed no `.cargo` file for `api:check`, and a comment added to the file left the key unchanged, while the same file not ignored was listed and the comment changed the key.
2121
+ - **Ignored configuration and the keys.** In other copies of `patched-workspaces`, with the root manifest as committed, whose `[patch]` redirects `fork` to `third_party/fork`, and with the daemon and `api:build` cached, a `[patch]` of `fork` to `third_party/fork-b` written into a `rust/.cargo/config.toml` that `.gitignore` left out, where `fork-b` is a crate of the same name, version and dependencies, left `Cargo.lock` unchanged after the lockfile task, and `nx run api:build` restored the result built with `third_party/fork`, "existing outputs match the cache, left as is", while `cargo tree -p api` showed `third_party/fork-b`. The same `[patch]` in the Cargo home's `config.toml` gave the same hit. Without the daemon, the graph followed the change and the task ran and compiled `fork-b`. Without the daemon too, an `[env]` value that `env!` read in `plain`, changed in a `rust/.cargo/config.toml` that `.gitignore` left out, gave a cache hit, where the same change in a file that Nx reads made `plain:build` run.
2122
+
2123
+ The fixture `patched-workspaces` keeps the cases that need no registry, and `nx-rust/test/redirections.spec.ts` checks with `cargo tree --offline --locked` that every crate with a project that cargo builds for a member is reachable from it in the graph. The workspaces were toys, so this says nothing about how long reading the files takes in a large repository.
2124
+ :::
2125
+
2126
+ :::mara evidence EVD-NX-24-INPUTS-OUTPUTS
2127
+ :mid: 01M7AT8XZ93BXDYFHRTR7WF434
2128
+ :title: What Nx 24.0.6 does with the plugin's inputs, outputs and dotenv files
2129
+ :status: accepted
2130
+ :supports: DES-INPUTS
2131
+ :supports: DES-OUTPUTS
2132
+ :supports: DES-DIAGNOSTICS
2133
+
2134
+ Experiments on 13 November 2026 with the `nx` 24.0.6 package that this repository installs, cargo and rustc 1.100.0, Node 26.12.0 and rustup 1.29.3, on Linux x86-64, through the cache-key harness of `nx-rust/test` (`nx-rust/test/README.md`): in a copy of a fixture, Nx's own `createProjectGraphAsync`, `createTaskGraph` and task hasher built the graph and the task hashes with `NX_DAEMON=false`, `RUSTUP_AUTO_INSTALL=0` and the plugin loaded from source. A reading of that package went with them; paths below are under `dist/src/`, and a point marked "read" was not run.
2135
+
2136
+ - **A named input that a dependency lacks.** A crate whose `project.json` gave it an implicit dependency on a JS project, its own named input `cargoCrate`, and the inputs `cargoCrate` and `^cargoCrate` on a target, failed the hash with `Input 'cargoCrate' is not defined`. Nx expands a `^` input with the named inputs of each project that the task's project depends on, and those are Nx's own `default`, `{projectRoot}/**/*`, then those of `nx.json`, then the project's own (`getNamedInputs` and `expandNamedInput` in `hasher/task-hasher.js`, read). Every project therefore has a `default`.
2137
+ - **Executors.** Hashing a task looks up its executor in every case, for a custom hasher (`getCustomHasher` in `tasks-runner/utils.js`, called from `hasher/hash-task.js`). A target whose executor's package declares no executors failed the hash with `Unable to resolve @convesoft/nx-rust:cargo. The "@convesoft/nx-rust" package does not support Nx executors.` `nx show target inputs` takes that failure as "no custom hasher" and lists the inputs (`hasCustomHasher` in `command-line/show/show-target/utils.js`, read).
2138
+ - **Outputs.** `getOutputsForTargetAndConfiguration` (`tasks-runner/utils.js`) interpolates an output from the task's options, with the tokens of `tasks-runner/tokens.js`, in which `{options.a ?? b}` falls back to the literal `b` when the option has no value, and then normalises the path. Called directly, `{workspaceRoot}/rust/target/{options.targetTriple ?? .}/{options.profile ?? debug}/api` gave `rust/target/debug/api` without options, `rust/target/release/api` with `profile: "release"`, and `rust/target/x86_64-unknown-linux-gnu/release/api` with that `targetTriple` as well. An output whose `{options.…}` token keeps no value is dropped, and a target named `build` without `outputs` gets `dist/{projectRoot}`, `{projectRoot}/dist`, `{projectRoot}/build` and `{projectRoot}/public` (read).
2139
+ - **A task's dotenv files.** `getTaskSpecificEnv` (`tasks-runner/task-env.js`) loads the dotenv files of a task only when `NX_LOAD_DOT_ENV_FILES` is `true`, which `nx run`, `nx run-many` and `nx affected` set unless it is `false` (`setEnvVarsBasedOnArgs` in `tasks-runner/run-command.js`, read). With the variable set, `RUSTUP_TOOLCHAIN=1.91.0` in a crate's `.env`, which `.gitignore` listed, changed the keys of that crate's tasks and of no other crate of its workspace, and a toolchain name that rustup cannot have gave a new key at each hash while the keys of the other crates stayed the same. Without the variable, as the harness first hashed, neither changed a key.
2140
+ - **The toolchain of one workspace.** With a `rustc` first on `PATH` that printed a value of its own in the folder `backend` and ran the real `rustc` elsewhere, a new value changed the keys of the crate in `backend` and not those of the crate in `shared` that it depends on. The command `cd './backend' && RUSTUP_AUTO_INSTALL=0 rustc -Vv 2>/dev/null || od -An -N16 -tx1 /dev/urandom` thus ran per task, in the folder it names.
2141
+ - **npm nodes from a pnpm lockfile.** With a root `package.json` and a `pnpm-lock.yaml` in pnpm 9's format written by hand, Nx's JS plugin made an npm node of each package listed, `npm:@convesoft/nx-rust` among them, and `externalDependencies: ["@convesoft/nx-rust"]` hashed that node and `npm:tslib@2.9.1` behind it: a new integrity of `tslib` changed the key, one of `left-pad` did not. Without `node_modules/.modules.yaml`, which a pnpm install writes, graph creation failed with "pnpm lockfile detected, but … node_modules/.modules.yaml is missing" (`plugins/js/lock-file/utils/pnpm-normalizer.js`).
2142
+ - **Files that Nx sees.** `globWithWorkspaceContext` (`utils/workspace-context.js`), which Nx's own plugins call in `createNodes`, returned the manifest of a path dependency only while no `.gitignore` listed its folder; it asks the daemon where one serves the command (read).
2143
+
2144
+ No executor of the plugin ran: this shows what Nx hashes and declares for targets of this shape, not what a run stores or restores.
2145
+ :::
2146
+
2147
+ :::mara evidence EVD-CARGO-DEPENDENCY-SIDE
2148
+ :mid: 01M7AXS7AZFTFJX9Y61GK0Z37B
2149
+ :title: What cargo applies from a dependency's side when another workspace builds it
2150
+ :status: accepted
2151
+ :supports: DES-INPUTS
2152
+
2153
+ Experiments on 13 November 2026 with cargo 1.100.0 and repeated with 1.91.0, on Linux x86-64, in a copy of the fixture `cross-workspace-path`: `server`, a member of the workspace in `backend/`, depends by path on `model`, a member of the workspace in `shared/`, and `cargo check -p server --offline` ran in `backend/` with `RUSTUP_AUTO_INSTALL=0` and an artifact directory of its own. Each case changed one file on `model`'s side and made `model`'s source fail to compile exactly when the change applied.
2154
+
2155
+ - **The dependency's workspace manifest applies.** `model` with `[lints] workspace = true` and `[workspace.lints.rust] unsafe_code = "forbid"` in `shared/Cargo.toml` failed to compile with an `unsafe` block, with both versions. The review of pull request #33 showed the same for `edition.workspace = true`: changing the edition in `[workspace.package]` of `shared/Cargo.toml` from 2021 to 2024 made `server`'s check fail on the reserved keyword `gen`.
2156
+ - **Its configuration and toolchain do not.** A `[build] rustflags = ["--cfg", "dep_side"]` in `shared/.cargo/config.toml`, and the same in `shared/.cargo/config`, left `#[cfg(dep_side)] compile_error!` unseen, and a `shared/rust-toolchain.toml` that names a toolchain rustup does not have failed nothing: cargo takes both from the folder it starts in, `backend/`.
2157
+ - **Nor do its profiles.** `[profile.dev] debug-assertions = false` in `shared/Cargo.toml`, and in `model`'s own manifest, left `#[cfg(not(debug_assertions))] compile_error!` unseen: cargo applies the profiles of the workspace it builds.
2158
+
2159
+ So what decides a dependency when another workspace builds it is its folder and its workspace's root manifest; the configuration, toolchain and profiles come from the consumer's own context.
2160
+ :::
2161
+
2162
+ :::mara evidence EVD-CARGO-UNREPORTED-CRATES
2163
+ :mid: 01M7B1MZ86KN4JWTFJCVPWY64E
2164
+ :title: Which path dependencies cargo builds but does not report
2165
+ :status: accepted
2166
+ :supports: DES-METADATA-REPORT
2167
+
2168
+ Experiments on 13 November 2026 with cargo 1.100.0 and 1.91.0 on Linux, which gave the same results. In each, a workspace `w1` had a member `app` with a path dependency on a crate `x` outside `w1`'s folder. The commands were `cargo check --offline` and `cargo metadata --format-version 1 --no-deps --offline` in `w1`, and the same report for `x`'s manifest through `--manifest-path`, also started in `w1`.
2169
+
2170
+ - **Not a member.** With `x` in the folder of a workspace `w2` whose `members` did not list it, `cargo check` succeeded and `x`'s report failed with "current package believes it's in a workspace when it's not", naming both manifests and the remedies: listing `x` in `members` or `exclude`, or an empty `[workspace]` table in `x`'s manifest. So it did with `x` in a subfolder of `w2` that named `w2` in `package.workspace`, and with `x` taking its `version` from `w2`'s `[workspace.package]`. The fixture `cross-workspace-path` with `members = []` in `shared/Cargo.toml` behaved the same.
2171
+ - **Its workspace broken elsewhere.** With `x` in `w2`'s folder while `w2` listed a missing member, with `package.workspace` naming a manifest without `[workspace]`, and with `package.workspace` naming a missing folder, `cargo check` succeeded and `x`'s report failed with "failed to load manifest for workspace member", "root of a workspace inferred but wasn't a root" and "failed to read".
2172
+ - **The messages word for word.** Repeated on 14 November 2026 with cargo 1.100.0 and 1.91.0, which printed the same text. Cargo's error, the first line of its output that starts with `error:`, was ``error: failed to load manifest for workspace member `<w2>/missing` `` followed by ``referenced by workspace at `<w2>/Cargo.toml` `` and the causes ``failed to read `<w2>/missing/Cargo.toml` `` and "No such file or directory (os error 2)", both where `w2` listed `x` beside the missing member and where it listed only the missing member. For the other two it was `error: root of a workspace inferred but wasn't a root: <manifest>`, naming the manifest without `[workspace]`, and ``error: failed to read `<folder>/Cargo.toml` `` with the cause "No such file or directory (os error 2)". So it was with `x` in the folder of a crate `p` whose `package.workspace` named such a manifest or folder, where `x` had none, and with `package.workspace` naming a `Cargo.toml` that existed but that cargo could not read, whose cause was "Permission denied (os error 13)"; in each, `cargo check` succeeded.
2173
+ - **The same messages below another error.** With `x` taking its `version` from the workspace that its `package.workspace` names, a manifest without `[workspace]` or a missing folder, and reached through a crate `z` outside `w1` that depends on it, `cargo check` in `w1` failed, while the reports of `w1` and `z` succeeded. `x`'s report failed with ``error: failed to parse manifest at `<x>/Cargo.toml` `` and the causes "error inheriting `version` from workspace root manifest's `workspace.package.version`" and then "root of a workspace inferred but wasn't a root" or "failed to read". With `x`'s own manifest unreadable, `cargo check` failed and `x`'s report failed with ``error: failed to read `<x>/Cargo.toml` `` and "Permission denied (os error 13)". A `Cargo.toml` that is a folder gave "manifest path … is a directory but expected a file", and one that is no valid UTF-8 gave "path at … was not valid utf-8".
2174
+ - **A manifest that cargo rejects.** With `x`'s manifest no valid TOML, missing, or inheriting a key that its workspace does not define, `cargo check` failed and so did `w1`'s own report, which reads the manifest of each member's path dependency outside the workspace's folder. With `x` a valid workspace of its own that depends by path on a crate `y` whose manifest is no valid TOML, `cargo check` failed while the reports of `w1` and `x` succeeded and `y`'s failed. With `x` a member of `w2` that depends by path on a missing member of `w2`, `cargo check` failed and `x`'s report failed with "failed to load manifest for workspace member", the message of the case above in which `cargo check` succeeded. With `x` a non-member of `w2` that depends on such a `y`, `cargo check` failed and `x`'s report failed with the membership message, before cargo read `y`.
2175
+ - **Redirections through it.** In a copy of the fixture `patched-workspaces` in which the member `plain` depended by path on a non-member of another workspace's folder that declared `model = "0.1"`, `cargo tree -p plain --offline` showed that crate using the `model` to which `rust/Cargo.toml` redirects. In the reproduction of the review of pull request #42, a workspace whose root manifest redirected its members `server` and `b` to themselves, with `server` depending on a vendored registry crate `wrapper` that depends on `b`, and `b` depending by path only on a vendored crate `leaf` without a report, `cargo check -p server` succeeded and `cargo tree -p server` showed `server -> wrapper -> b -> leaf`.
2176
+
2177
+ So the membership message says by itself that the failure is one that cargo does not make for a crate it builds as a dependency, and so do "root of a workspace inferred but wasn't a root" and "failed to read" for a manifest other than `x`'s own as cargo's error itself; below another error they come where cargo rejects `x` as a dependency too. The message about a workspace member also comes when cargo rejects a crate that `x` needs.
2178
+ :::
2179
+
2180
+ :::mara evidence EVD-CARGO-TRIPLE-FOLDERS
2181
+ :mid: 01M7BGGY6GSG8M0H26G1H71RVN
2182
+ :title: Where cargo puts artifacts and documentation for each way a triple is picked, and how Nx names them
2183
+ :status: accepted
2184
+ :supports: ADR-TRIPLE-OUTPUTS
2185
+ :supports: DES-OUTPUTS
2186
+ :supports: DES-BUILD-INPUT-CHECK
2187
+
2188
+ Experiments on 13 November 2026 with cargo 1.100.0 (3acc79c0c 2026-11-05) and 1.91.0 (ea2d97820 2025-10-10), and where named 1.89, 1.97.1, 1.98 and 1.99.0, on Linux x86-64 with `RUSTUP_AUTO_INSTALL=0`, in a throwaway workspace outside this repository with a Cargo home of its own: a crate `app` with a library and a binary, a crate `cd` with the crate types `cdylib` and `staticlib`, and a profile `fast` that inherits `release`. The 1.100.0 toolchain had the targets `x86_64-unknown-linux-gnu`, the host's (H below), and `x86_64-unknown-linux-musl` (M) installed, among others, and 1.91.0 only the host's. `aarch64-unknown-linux-gnu` (A), installed for neither, stood for a triple that cargo cannot build for, so that a failure showed that cargo had picked it. Each case started without a `target` folder and ran `cargo build -p app` or `cargo doc --no-deps --workspace`. Both versions gave the same results unless one is named.
2189
+
2190
+ - **Folders.** Without a triple, the binary went to `target/debug` and the documentation to `target/doc`. With H given as `--target H`, as `CARGO_BUILD_TARGET=H` or as `build.target = "H"` or `["H"]` in `.cargo/config.toml`, they went to `target/H/debug` and `target/H/doc`, although H is the host's triple. `--release` and `--profile fast` gave `target/H/release` and `target/H/fast`, while the documentation stayed in `target/H/doc` with `--release`. `cd` gave `libcd.so` and `libcd.a` in `target/H/debug`. With 1.100.0, `build.target = ["H", "M"]` built into `target/H/debug` and `target/M/debug`, also with `--release`, and `cargo doc` wrote both `doc` folders. `["H", "H"]` built into `target/H` once. `host-tuple`, as the flag, the variable and the setting, built into `target/H`.
2191
+ - **Precedence.** `--target` replaced the variable and the setting: with `build.target = "A"`, or with `CARGO_BUILD_TARGET=A`, `--target H` built for H alone, and with `["H", "M"]` configured, `--target M` built for M alone. `CARGO_BUILD_TARGET` replaced a string: `"A"` with `CARGO_BUILD_TARGET=H` built for H, and `"H"` with M for M. Beside a list, the variable joined it: `["H"]` with `CARGO_BUILD_TARGET=M` built for H and M, `["H", "A"]` with H failed on A, and `"M H"` added both words. Without a list, the whole value was one triple: `CARGO_BUILD_TARGET="H H"` and `'["H"]'` failed with "failed to run `rustc` to learn about target-specific information". An empty variable, and `build.target = ""`, failed with "target was empty", while an empty variable beside a list added nothing. `build.target = []` built nothing and succeeded; with `CARGO_BUILD_TARGET=M` it built for M.
2192
+ - **Several files.** A string in the workspace's `.cargo/config.toml` won over one in the folder above and over one in the Cargo home's `config.toml`, and either of those alone applied. Lists in the files of the workspace and of the folder above were joined: `["M"]` above and `["H"]` in the workspace built for both, and `["A"]` above made the build fail. A string in one of the files and a list in the other failed every command, `cargo metadata` included, with "could not load Cargo configuration" ("expected array, but found string"), and so did `build.target = 5`; `cargo metadata` accepted `""`. Of `.cargo/config` and `.cargo/config.toml` in one folder, `.cargo/config` won.
2193
+ - **include.** Cargo 1.89 and 1.91.0 ignored `include = ["extra.toml"]`: a triple set only in the included file left the artifacts in `target/debug`. Cargo 1.97.1, 1.98, 1.99.0 and 1.100.0 applied it. With 1.100.0, the including file's string won over the included file's, a later include over an earlier one, an included list joined the including file's list, and a file that the folder above includes applied where the workspace set nothing; the string `include = "extra.toml"` failed with "expected a list of strings or a list of tables". The Cargo book of the 1.100.0 toolchain gives the same order ("Including extra configuration files"); that of 1.91.0 has no `include`.
2194
+ - **Asking cargo.** No stable command reports the triples. `cargo config get build.target` failed with both versions: "the `cargo config` command is unstable, and only available on the nightly channel". The `cargo metadata` report has no triple among its keys.
2195
+ - **Nx 24.0.6.** In this repository's harness, with `NX_DAEMON=false`, a change of nothing but the literal in `{options.t ?? aaa}` in one target's `outputs` changed the hash of the project's configuration, and with it the key of every task of the project. Read in the installed package (paths under `dist/src/`): `getOutputsForTargetAndConfiguration` (`tasks-runner/utils.js`) collects the interpolated outputs in a set, so equal outputs count once; a fallback after `??` applies to an empty option as to a missing one (`resolveToken` in `tasks-runner/tokens.js`); and in an output `env.` stays text, so no output reads an environment variable (`interpolate` in `tasks-runner/utils.js`). The `nx` command loads the root `.env`, `.local.env` and `.env.local` into its own environment before it creates the graph (`bin/workspace-env.js`, `loadRootEnvFiles` in `utils/dotenv.js`), and the other dotenv files of a task only for the task (`getEnvFilesForTask` in `tasks-runner/task-env.js`).
2196
+ - **The daemon.** On 14 November 2026, in `crate-shapes` with `NX_DAEMON=true`, plugins in workers and `CARGO_HOME` a folder beside the repository copy, with the outputs of [[DES-OUTPUTS]] but no triple input: `build.target` was set to H in the Cargo home's `config.toml`, or in a `.cargo/config.toml` above the repository, and `cli:build` and `rust:doc` ran. The setting was then changed to M, or removed, and `rust/target` deleted. The next runs were cache hits that put back the artifacts of H, and the outputs still named H, while a plain cargo wrote to `target/M`. The daemon kept its graph because it watches no file outside the repository, and deleting the ignored `rust/target` woke no watcher. A change through the environment, or through a configuration file inside the repository, gave a new key. With the triple input of [[DES-INPUTS]], each of those runs was no hit and failed before cargo ran. After `nx daemon --stop`, the tasks built into the folder of M, or of no triple, and were restored from there.
2197
+ - **Runtime inputs.** Two runtime inputs whose commands differed only in their text, `echo same` and `echo same`, gave the same key, and one with other output gave another: Nx hashes what the command prints and not the command, and a target's `inputs` are no part of the project's hashed configuration. In `crate-shapes`, `nx run-many -t build doc` evaluated the triple input, one command for all six tasks, six times, with the daemon and without, in plugin workers and in Nx's own process. One evaluation took about 16 ms, 12 to 14 ms of which was the start of Node. A fully cached `nx run-many -t build doc` over `two-workspaces`, six tasks, took a median of 493 and 502 ms with the input against 464 and 458 ms without it, in two rounds on a shared machine.
2198
+ - **Runs.** With the outputs that [[DES-OUTPUTS]] names and the cargo first on `PATH` (1.100.0), in the `crate-shapes` fixture with `NX_DAEMON=false`: `cli:build` and `rust:doc` were run, the binary and the doc folders deleted, and the tasks run again. Nx restored them without a cargo call, each file byte for byte as cargo had written it, for `build.target` set to H, to `["H", "H"]` and to `["H", "M"]`, both folders, and for `CARGO_BUILD_TARGET=H` in the environment of the `nx` command; and `cli:build` with H configured, where a configuration of the target names a triple or clears the triple of its options. A list of two triples was not built with 1.91.0, which has no second target installed.
2199
+ :::
2200
+
2201
+ :::mara evidence EVD-NX-24-MOVED-ARTIFACT-DIRS
2202
+ :mid: 01M7CKYHWJGAN6S9J3GRE4PKWV
2203
+ :title: What Nx stores and restores when a task's artifact directory moves after graph creation, and what following it costs
2204
+ :status: accepted
2205
+ :supports: ADR-ARTIFACT-DIR-OUTPUTS
2206
+ :supports: DES-OUTPUTS
2207
+ :supports: DES-INPUTS
2208
+ :supports: DES-BUILD-INPUT-CHECK
2209
+
2210
+ Experiments on 14 November 2026 with Nx 24.0.6 and cargo 1.100.0 on Linux x86-64, with `RUSTUP_AUTO_INSTALL=0` and a Cargo home of their own.
2211
+
2212
+ - **Dotenv files of a task.** In a throwaway repository with a Cargo workspace `rust/` and one binary crate `app`, the plugin compiled from this repository at commit d633767, `NX_DAEMON=false` and a private `NX_CACHE_DIRECTORY`: `nx show project` named the outputs of `build` in `rust/out` where the root `.env` set `CARGO_TARGET_DIR=out` or `CARGO_BUILD_TARGET_DIR=out`, and in `rust/target` where only a root `.env.build`, `rust/app/.env` or `rust/.env` set it. Read in the installed package: Nx loads the root `.env`, `.env.local` and `.local.env` for every command, before it creates the graph, and for a task, from the project's folder and then the root, `.env.<target>.<configuration>`, `.env.<configuration>`, `.env.<target>`, `.env.local`, `.local.env` and `.env`, with their `.local` and `.<id>.env` variants (`tasks-runner/task-env.js`, `task-env-paths.js`). Cargo wrote to `rust/out` with `CARGO_BUILD_TARGET_DIR=out`, and `CARGO_TARGET_DIR` won where both were set; `CARGO_BUILD_BUILD_DIR=bd` kept the intermediate files in `rust/bd` and the artifacts in `rust/target`; `cargo metadata --no-deps` reported both directories.
2213
+ - **What Nx stored.** With a git-ignored `rust/app/.env`: without the file, source v1 was built and stored; with `CARGO_TARGET_DIR=out` in it, the next run was a cache hit, its key unchanged; after the source changed to v2, cargo wrote `rust/out/debug/app`, and the cache entry held the v1 binary at `rust/target/debug/app` under v2's key, without a warning; with `target` and `out` deleted and the file removed, Nx restored that binary, which printed `app v1` where plain cargo built `app v2`. Without an older file at the declared path, the run succeeded and stored no file, and the next run without the dotenv file was a hit that restored no binary. `rust:doc` with `CARGO_TARGET_DIR=out` in `rust/.env` restored the pages of an older source in the same way. `CARGO_TARGET_DIR`, `CARGO_BUILD_TARGET_DIR` and `CARGO_BUILD_BUILD_DIR` in `rust/app/.env` or a root `.env.build` left the key of `app:build` as it was, `CARGO_PROFILE_DEV_OPT_LEVEL=1` there changed it, and `CARGO_TARGET_DIR` in the shell changed it through the outputs.
2214
+ - **The build input check.** With the dotenv file moving the artifact directory and `rust/target` deleted, a build that read an undeclared file succeeded and was cached, because the check found no record where graph creation's report put them; with an older record there, the check read that one. With `CARGO_BUILD_BUILD_DIR=bd` in the file and a library that includes a file from `OUT_DIR`, the check failed and named the file that the build script generated in `rust/bd`.
2215
+ - **The daemon.** On the branch of pull request #59, in the `crate-shapes` fixture with `NX_DAEMON=true` and `CARGO_HOME` a folder beside the repository copy, with `build.target-dir` in the Cargo home's `config.toml` set to the copy's `rust/target/a`, `cli:build` wrote `rust/target/a/debug/cli`. After the setting was changed to `rust/target/b` and `rust/target/a` deleted, the next run was a cache hit that put back `rust/target/a/debug/cli`, the outputs still named `rust/target/a`, and plain cargo wrote to `rust/target/b`. The folders lay inside the ignored `rust/target`; deleting an unignored `rust/target-a` instead woke the daemon's watcher, which created the graph afresh.
2216
+ - **With the artifact folder input and the executor's check.** In this repository's harness, `artifact-folders.spec.ts` and `build-input-check.spec.ts`: each daemon case, `build.target-dir` in the Cargo home's configuration or in one above the repository changed to another folder or removed, gave `cli:build` and `rust:doc` no cache hit, nothing in `rust/target/a`, no cargo build and the `nx reset` message, and after `nx daemon --stop` both were built into the new folder and restored from there. Each dotenv case, the crate's `.env`, a root `.env.build`, the `.env.fast` of a configuration that the run selected, the workspace folder's `.env`, and a root `.env.doc` setting `CARGO_HOME` to a home whose configuration sets `build.target-dir`, failed before cargo built and named both folders. The four steps above ended with the binary of v2. `CARGO_BUILD_BUILD_DIR=bd` in the crate's `.env` failed no build. With the executor's check disabled, nine of these tests failed.
2217
+ - **Cost.** `cargo metadata --no-deps --format-version 1` through the rustup proxy took about 6 ms in `two-workspaces`, and starting Node about 12 ms. A fully cached `nx run-many -t build doc` over `two-workspaces`, six tasks, with the rustup proxy on `PATH`, took medians of 606, 514, 434, 416 and 413 ms without the artifact folder input, and 565, 552, 553, 442 and 429 ms with it, in five alternating rounds on a shared machine whose load fell over the rounds; the two quietest pairs differ by 13 and 26 ms. With the harness's cargo wrapper, a Node script that logs each call, it took 491 and 504 ms against 705 and 741 ms.
2218
+ - **A change during a command.** In the review of this change on 14 November 2026, under the Nx daemon with `build.target-dir` in the Cargo home's configuration, the configuration was changed from one folder to another before a run, and a cargo wrapper changed it back just before the executor's `cargo metadata` call, after Nx had computed the task's key with the second folder. The task passed the check, built into the first folder, and Nx stored those artifacts under the key computed for the second.
2219
+ - **What Nx offers.** Nx 24.0.6 exports `getGraphTimeDotEnvForTask` from `nx/src/devkit-internals`, which its source describes for plugins whose inferred targets depend on a task's dotenv files, and its daemon creates the graph afresh when a dotenv file under the root or a project's folder changes (`daemon/server/dotenv-graph-changes.js`). No installed `@nx` plugin uses it.
2220
+ :::
2221
+
2222
+ :::mara evidence EVD-CARGO-COMPILER-SELECTION
2223
+ :mid: 01M7CMKMP5A6X62T5HNG5582R3
2224
+ :title: Which compiler and rustdoc cargo runs when a setting names one, and what the key held for them
2225
+ :status: accepted
2226
+ :supports: DES-INPUTS
2227
+ :supports: ADR-WORKSPACE-ROOT
2228
+ :supports: REQ-TOOLCHAIN-KEY
2229
+
2230
+ Experiments on 14 November 2026 on Linux x86-64 with rustup 1.29.3, cargo 1.100.0 (3acc79c0c 2026-11-05) of the default toolchain, and the toolchains 1.97.1 and 1.91.0, with `RUSTUP_AUTO_INSTALL=0`, a Cargo home of their own and nothing downloaded. A throwaway repository outside this one held a Cargo workspace `rust/` with one crate, `app`, a library with a doctest and a binary. Compilers were named through symbolic links to the toolchains' `rustc` and `rustdoc`; moving a link to another toolchain stood for `rustup update` replacing the compiler of a channel's path. Which compiler built the binary came from its ELF `.comment` section, which rustdoc wrote the pages from their `data-rustdoc-version`. A researcher ran the same cases that morning with the plugin at d633767; the rows below were run again for this item at 2d02d59, and those marked † come from that first run only.
2231
+
2232
+ **Which compiler cargo 1.100.0 runs** (`cargo build` in `rust/`):
2233
+
2234
+ | Setting | Compiled by |
2235
+ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2236
+ | none | 1.100.0 |
2237
+ | `RUSTC` naming 1.91 | 1.91.0 |
2238
+ | `CARGO_BUILD_RUSTC` naming 1.91 | 1.91.0 |
2239
+ | `RUSTC` 1.100 with `CARGO_BUILD_RUSTC` 1.91, and the other way round | 1.100.0, then 1.91.0: `RUSTC` wins |
2240
+ | `RUSTC=""` or `CARGO_BUILD_RUSTC=""`, or `RUSTC` naming a missing file | cargo fails: "could not execute process" |
2241
+ | `RUSTC=../../bin/rustc-91`, `RUSTC=rustc-97` with its folder on `PATH` | 1.91.0, 1.97.1: a path with a `/` counts from the folder cargo starts in, a bare name through `PATH` |
2242
+ | `build.rustc` naming 1.91 in `rust/.cargo/config.toml`, in the repository's `.cargo/config.toml`, or in the Cargo home's `config.toml` | 1.91.0 in each |
2243
+ | `build.rustc` 1.91 in `rust/.cargo` and 1.97.1 in the repository's `.cargo` | 1.91.0: the deeper file wins |
2244
+ | `build.rustc` 1.97.1 in a `.cargo/config.toml` above the repository and 1.91 in the Cargo home | 1.97.1 |
2245
+ | `build.rustc` 1.91 in a file, with `CARGO_BUILD_RUSTC` or `RUSTC` naming 1.97.1 | 1.97.1 |
2246
+ | `build.rustc = "rustc-91"` with its folder on `PATH`; `"../bin/rustc-91"` in the repository's `.cargo`; `"bin/rustc-91"` in the Cargo home's `config.toml` | 1.91.0 in each: a relative path counts from the folder that holds `.cargo`, for the Cargo home from its parent |
2247
+ | `build.rustc` 1.97.1 only in a file that `include` adds | 1.97.1 with cargo 1.100.0 and 1.97.1, 1.91.0 with cargo 1.91.0, which ignores `include` |
2248
+ | `build.rustc` 1.91 beside an include that names 1.97.1 | 1.91.0: the including file wins |
2249
+ | `build.rustc = "../../../bin/rustc-91"` in `rust/.cargo/sub/x.toml`, which `rust/.cargo/config.toml` includes | 1.91.0, while `"../../bin/rustc-91"` named a missing file: the path counts from the folder above the included file's, `rust/.cargo` |
2250
+ | `cargo +1.91.0 build` with `RUSTC` naming 1.97.1 | 1.97.1: `RUSTC` beats `+toolchain` |
2251
+ | `build.rustc` naming a link to 1.97.1 in the repository's `.cargo/config.toml`, which `tools/.cargo/config.toml` also includes, before an `extra.toml` naming 1.100.0 | 1.100.0 with cargo 1.100.0; 1.97.1 with cargo 1.91.0, also through `RUSTUP_TOOLCHAIN=1.91.0`. With the include of that file alone, 1.97.1 with both, and no error about a file loaded twice |
2252
+
2253
+ - **Precedence.** `RUSTC` before `CARGO_BUILD_RUSTC` before `build.rustc`, of which the deepest file wins and the Cargo home comes last, before the `rustc` that rustup or `PATH` gives. Cargo passes the compiler it runs to build scripts as `RUSTC`.
2254
+ - **A file of the walk that a deeper file includes.** It counts in its own place for every version, as the folder above's file does for Cargo 1.91, which ignores `include`; later versions also read it where the deeper file includes it, with that file's precedence. The same shape for `build.target`, with the repository's file naming `x86_64-unknown-linux-gnu`, `extra.toml` and the Cargo home's `config.toml` naming `aarch64-unknown-linux-gnu`: cargo 1.91.0 built into `target/x86_64-unknown-linux-gnu`, and cargo 1.100.0 picked `aarch64-unknown-linux-gnu` and failed for want of its standard library.
2255
+ - **Rustdoc.** `RUSTDOC`, `CARGO_BUILD_RUSTDOC` and `build.rustdoc` naming 1.91 each made `cargo doc` write pages of rustdoc 1.91.0, and `cargo test --doc -v` run the doctests with that rustdoc. With only `RUSTC` naming 1.91, `cargo doc` still used rustdoc 1.100.0, that of the default toolchain. An empty `RUSTDOC` failed `cargo doc`. † After documenting with `RUSTDOC` naming 1.91, a plain `cargo doc -v` printed `Fresh app` and kept the 1.91 pages: cargo does not document again when only rustdoc changes.
2256
+ - **Wrappers.** † A `RUSTC_WRAPPER` that logged its arguments saw `<wrapper> …/rustc -vV` and the compile commands; `RUSTC_WORKSPACE_WRAPPER` the same once cargo's cached compiler information was invalidated. A wrapper that dropped its first argument and ran 1.91 produced a 1.91.0 binary under either variable.
2257
+ - **Asking cargo.** † No stable command reports the compiler: `cargo config get` and `cargo rustc --print sysroot` are nightly-only, and `cargo rustc -- -vV` builds the crate first. The plugin's executor starts `cargo` without `+toolchain`, so only `RUSTUP_TOOLCHAIN` chooses a toolchain that way.
2258
+ - **The old toolchain command.** `rustc -Vv` in `rust/` with `RUSTC` naming 1.97.1 printed `release: 1.100.0`.
2259
+
2260
+ **What the key held before** (the plugin's inferred targets, Nx 24.0.6's own hasher, the daemon off): `RUSTC` and `CARGO_BUILD_RUSTC` reached the key only as the text of their `env` inputs, and `build.rustc` only through the text of a configuration file inside the repository; the researcher found the keys the same for `build.rustc` in the Cargo home and above the repository. The cases of [[VER-CACHE-KEYS]] for these settings were then run as tests of this repository at 2d02d59, with a toolchain command that printed what the one of that commit prints, and each failed:
2261
+
2262
+ | Change, with every file and variable the same | Keys |
2263
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
2264
+ | the link that `RUSTC` names moved from 1.91.0 to 1.100.0 | same for `build`, `check`, `lint`, `test`, `fmt-check` and `doc` |
2265
+ | the same through `CARGO_BUILD_RUSTC`, through `build.rustc` in `rust/.cargo/config.toml`, in a `.cargo/config.toml` above the repository or as a relative path, and through `RUSTC` in a crate's `.env` | same |
2266
+ | the link that `RUSTDOC` names moved | same for `doc` and `test` |
2267
+ | `build.rustc` naming 1.91 added to the Cargo home's `config.toml`, then its link moved | same, both times |
2268
+ | `RUSTC=""`, `CARGO_BUILD_RUSTC=""`, `RUSTC` naming a missing file, or `build.rustc` naming one | repeated from one evaluation to the next |
2269
+
2270
+ **End to end before**, `nx run tools:build` in the harness's `two-workspaces` with the daemon off, `tools` printing the version of the compiler that built it: with `RUSTC` naming a link to 1.91.0, the first run built with 1.91.0; after the link was moved to 1.100.0 and the binary deleted, the second run printed `[local cache]` and restored the 1.91.0 binary. With nothing set the first run built with 1.100.0; after `build.rustc` naming 1.91.0's rustc was written to the Cargo home's `config.toml` and the binary deleted, the second run printed `[local cache]` and restored the 1.100.0 binary. The researcher's runs at d633767 restored the same way, while plain cargo built with the new compiler.
2271
+
2272
+ **A shape the first version missed.** A review of pull request #66 found that the first version of the reading recorded a file of the walk that a deeper file had already included only as included, so the compiler that Cargo 1.91 runs there was not asked. In `two-workspaces`, with the repository's `.cargo/config.toml` naming a link to 1.91.0, `tools/.cargo/config.toml` including it and then an `extra.toml` naming 1.100.0, `RUSTUP_TOOLCHAIN=1.91.0` and an empty Cargo home, moving the link to 1.97.1 left all six cached keys of `tools` the same, and `tools:build` restored a 1.91.0 binary where plain cargo compiled with 1.97.1. The reading of `build.target` at 2d02d59 has the same flaw: for the shape above with the Cargo home also naming `aarch64-unknown-linux-gnu`, it named that triple, the folder cargo 1.91.0 does not write to; with an empty Cargo home it named none, rightly, the two readings differing; and with the include of the repository's file alone it named none where both versions build for `x86_64-unknown-linux-gnu`. Read as cargo reads it, with a record of included files for each file of the walk, the input asks both compilers, and the triple reading names `x86_64-unknown-linux-gnu` for the include alone and none for the other two; tests of both readers, of the keys with the real hasher and a real run of `tools:build` failed on the first version and pass.
2273
+
2274
+ **With the toolchain input of [[DES-INPUTS]]**, which runs `rustc -Vv` and then `-Vv` of the compiler, and on `doc` and `test` of the rustdoc, that a setting names, the same tests passed: each change gave other keys, a crate's `.env` only those of its crate, `RUSTDOC` only those of `doc` and `test`, and the failing cases a new key at each evaluation; another toolchain through `RUSTUP_TOOLCHAIN` changed the keys while `RUSTC` named a compiler. Both runs above built again with the new compiler and restored nothing. Without any of these settings, the hasher gave each of the 43 cached tasks of `subfolder-workspace` and `two-workspaces`, with and without a `CARGO_PROFILE_` variable, the same value for every input as at 2d02d59, apart from the `nx.json` that the harness writes for each test run, among them the toolchain input, whose command text had changed: Nx keys a runtime input on what it prints.
2275
+
2276
+ **When each part is known**, as read in Nx 24.0.6 (paths under `dist/src/`) and in [[EVD-NX-24-INPUT-SEMANTICS]]: graph creation sees the `nx` command's environment with the root `.env`, `.local.env` and `.env.local` (`bin/workspace-env.js`), which the daemon takes from the client, and reads configuration files from disk; a runtime input and the task's cargo see the task's environment with its dotenv files (`getTaskSpecificEnv` in `tasks-runner/task-env.js`). A researcher's run showed `RUSTC` in a crate's git-ignored `.env` reach both. So the variables reach the command at hash time, while what graph creation resolves from configuration files outside the repository can be out of date under the daemon, which watches no file there ([[EVD-CARGO-TRIPLE-FOLDERS]]).
2277
+
2278
+ One `rustc -vV` took 5 to 6 ms through a direct path and 7 to 13 ms through the rustup proxy. Not covered: a daemon run with these settings, macOS, the cost in a large workspace, and `rustup update` itself, which the moved links stood for.
2279
+ :::
2280
+
2281
+ :::mara evidence EVD-NX-24-PROCESS-STATE
2282
+ :mid: 01M7D46BY7J43Y6H0X99D5V5N0
2283
+ :title: What Nx 24.0.6 keeps in a process between two graph or hash computations, and what one test session per fixture saves and costs
2284
+ :status: accepted
2285
+
2286
+ A reading of the `nx` 24.0.6 package that this repository installs (paths under `dist/src/`), and experiments on 14 November 2026 with it, Node.js 26.12.0, cargo 1.100.0 and git 2.56.0 on Linux, on a machine with 32 cores and 14 GB of memory that other test runs shared. The experiments asked the questions of the harness's `inspect-workspace.cjs`, the project graph, task hashes with their details, the files of a task's key and Nx's glob, in fixture copies that load the compiled plugin into Nx's own process (`NX_ISOLATE_PLUGINS=false`) without the daemon: once in a fresh process per request, as the harness does, and once in one process that stayed up in the copy's root and answered request after request, a session. The session's code is the first commit of pull request #76.
2287
+
2288
+ - **What a process keeps.** The workspace root is fixed when Nx is loaded (`utils/workspace-root.js`, line 12), and so are the cache and workspace data folders derived from it (`utils/cache-directory.js`, lines 402 and 410): `setWorkspaceRoot` changes the root but not those folders, so one process serves one root. Nx resets some of its state itself: every graph without the daemon walks the files again (`refreshWorkspaceContext`, `project-graph/project-graph.js`, line 97), `resetWorkspaceContext` drops the native workspace context (`utils/workspace-context.js`, line 275), and `cleanupPlugins` drops the loaded plugins (`project-graph/plugins/get-plugins.js`, line 266), whose modules stay in Node's module cache with their state. Other state has no reset outside a new process. `getTaskSpecificEnv` keeps each task's environment, dotenv files included, by task id for the life of the process, which its comment calls one command and never the daemon (`tasks-runner/task-env.js`, lines 57 to 62). The capabilities store opens a connection to the database in the workspace's `.nx/workspace-data` when it first writes there and keeps it (`project-graph/plugins/nx-plugin-capabilities.js`, lines 8 and 15). A graph creation without the daemon writes there only when it succeeds and the project-graph cache is on, which `NX_CACHE_PROJECT_GRAPH=false` turns off (`project-graph/project-graph.js`, lines 120 and 146 to 150). The harness leaves that variable unset, so in a fixture every graph creation that succeeds writes there, and a later one that fails leaves the connection open. `removeDbConnections` closes the connections but leaves the store holding its closed one (`utils/db-connection.js`, line 43). One graph and hash request loads 278 modules of Nx, whose module-level state also includes the npm resolution caches of the JS plugin (`plugins/js/project-graph/build-dependencies/target-project-locator.js`, lines 19 and 20). Each load of `native/index.js` replaces `process.emit` with a wrapper around the one before (lines 22 and 23). Nx's `performance.measure` calls throw where another request has cleared the marks they name. The plugin keeps module state of its own, such as the Nx majors it supports and the Nx internals it loaded for each workspace root.
2289
+ - **Reusing Nx's modules.** A session that kept Nx's modules and reset only the workspace context, the plugins and the plugin's modules gave the answers of fresh processes for unchanged files, changed files and a copy deleted and copied again, but after `RUSTFLAGS` changed, and after a crate's `.env` changed, it gave every key of `subfolder-workspace` unchanged where a fresh process changed it: the tasks' environments came from `taskSpecificEnvCache`.
2290
+ - **Loading Nx afresh for each request.** A session that, before each request after the first, closed Nx's database connections, dropped every module from Node's module cache but the native addon, so that Nx and the plugin loaded afresh, and put back the environment (Node writes `process.env` through to the process's environment, which the native addon and child processes read), the current folder, the functions and listeners that the request had added to `process`, the globals, `Error`'s stack trace settings and the performance timeline, gave the answers of fresh processes, below. Node, V8's caches of compiled code and Nx's native addon, which Node loads once per process, stay; so a request that changes a variable starting with `NX_` or `NODE_`, which Node reads at start and the addon may read once, still needs a fresh process, as does every request after one that changes how Node loads modules, such as by registering a TypeScript transpiler for a plugin loaded from source. Until `process.emit` was put back, each request kept every earlier request's modules alive, about 2.5 MB of heap a request.
2291
+ - **Same results.** With every request answered by a session and by a fresh process and compared value by value, graphs, hashes and every detail of each hash, all 197 tests of `cache-keys.spec.ts` and `declared-files.spec.ts` passed on `main` at fa40259, and all 199 on `main` at e8958bb, after pull requests #73, #74 and #75. The only values that differed were the toolchain inputs that print random bytes while the compiler is missing, such as with `RUSTC=changed`, in which two fresh processes differ as well. The files' `nx affected` and daemon commands ran in fresh processes.
2292
+ - **Time.** In `subfolder-workspace`, a fresh process took 320 to 410 ms to hash six tasks and about 200 ms for one; starting Node and loading Nx took about 70 ms of it, creating the graph about 105 ms, and hashing, with its runtime inputs and cargo calls, the rest. A session answered the same requests in 210 to 250 ms and about 65 ms, apart from its first request, which took as long as a fresh process. With one shared session workspace per spec file, replaced when a test asks for another fixture, each file run alone two to four times beside other test runs: on e8958bb, `cache-keys.spec.ts` (98 tests) took 57.2 s with fresh processes and 44.4 s with sessions, and started 50 Nx processes, 25 of them sessions, instead of 223; `declared-files.spec.ts` (101 tests) took 68.3 s and 53.8 s, and started 96 Nx processes, 3 of them sessions, instead of 268, of which 92 are `nx affected` and daemon commands. On fa40259 the files took 68.3 s and 53.7 s, and 72.5 s and 60.4 s.
2293
+ - **Memory.** A fresh process peaked at about 250 MB of resident memory, with and without `--enable-source-maps`, and at about 245 MB with `MALLOC_ARENA_MAX=2`. A session grew to 400 to 475 MB after 20 to 40 requests with `MALLOC_ARENA_MAX=2`, and to 384 to 405 MB with V8's semi-space limited to 1 or 2 MB as well. The peak of the anonymous memory of a run of one file rose from about 1030 to 1250 MB for `cache-keys.spec.ts` and from 1250 to 1380 MB for `declared-files.spec.ts`.
2294
+ - **Where the time of the unit tests goes.** A full unit run on e8958bb with fresh processes only took 223 s with three Jest workers, 588 s summed over the files. Of that, 867 graph, hash, file and glob requests took 205 s, 223 and 176 of them in the two files above, and 799 `nx` commands, runs of tasks among them, took 360 s; spec files that run no Nx in a fixture took 6 s. Beside the Nx processes, the run started Node 4680 times for the harness's cargo wrapper, about 17 ms each before cargo starts (a wrapped `cargo --version` took 23 ms against 4 ms), and 1179 times for the plugin's artifact folder input, which took about 53 ms with its cargo call through the wrapper.
2295
+
2296
+ The points marked with a source file were read, not run.
2297
+ :::
2298
+
2299
+ :::mara evidence EVD-NX-24-WORKSPACE-CONTEXT
2300
+ :mid: 01M7X4A8Z2V6GGBB2XEZEHF1HC
2301
+ :title: How long the workspace context of Nx 24.0.6 lists a process's files, and what clears it
2302
+ :status: accepted
2303
+ :supports: DES-BUILD-INPUT-CHECK
2304
+
2305
+ A reading of the `nx` 24.0.6 package that this repository installs (paths under `dist/src/`), and experiments on 20 November 2026 for nxr-1tmme6 with it, Node.js 26.12.0 and cargo 1.100.0 on Linux: throwaway repositories under the temporary folder, and runs of `nx` through the test harness in copies of the fixture `batch-groups`, with a module loaded through `NODE_OPTIONS` that logged each native `WorkspaceContext` made and each of its methods called, with the caller. They check a second opinion of the same day, which had read and run the same package, before the plugin relies on it.
2306
+
2307
+ - **One list per process.** `globWithWorkspaceContextSync` and `HashPlanInspector.init`, which calls `getNxWorkspaceFilesFromContext` with `useDaemonProcess` false, read the context that `utils/workspace-context.js` keeps at module level; neither asks the daemon. The context is made on first use (`ensureContextAvailable`, line 270) and kept. After a glob, a file written and a second glob, the second listed only the files of the first, also 1.5 seconds and another process's walk later; an inspector made after the write gave the input files of the first for `{projectRoot}/**/*`. A fileset with `includeIgnored` gave the new file, because Nx reads those from the disk ([[EVD-NX-24-FILESET-SCOPE]]), so a file that a crate's `fileInputs` declare does not depend on the context.
2308
+ - **`refreshWorkspaceContext`** walks again only where the daemon is not enabled for the process: it returns at once while `daemonClient.enabled()` is true, and also for the root `/virtual` and inside the daemon's own process (line 260), neither of which the check meets. With `NX_DAEMON=true`, a file written before it was missing after it; without the daemon, the walk listed it. A graph made without the daemon calls it (`project-graph/project-graph.js`, line 97).
2309
+ - **`updateFilesInContext`** hands the paths to the native `incrementalUpdate` as they are: `ign/x.txt`, below a folder that `.gitignore` lists, then appeared in the glob, which the walk leaves out.
2310
+ - **`resetWorkspaceContext`** stops a watching context, drops it and makes it again at once only where it watched, which only the daemon's does (line 275); otherwise the next read makes a new one, which gets its files then, as the next point says. After a write and the reset, the glob and a new inspector listed the file; the walk still left out what `.gitignore` and `.git/info/exclude` list. Nx calls it after it wrote files in `command-line/import/import.js` (line 201); the daemon calls it in `resetInternalState` (`daemon/server/project-graph-incremental-recomputation.js`, line 655), after an error while it recomputes the project file map (line 377) and when the cached graph it persisted has gone (line 667), which need no write of Nx's. `devkit-internals.js` exports it as well.
2311
+ - **One walk shared between processes.** Read in the source of the tag `24.0.6` (`packages/nx/src/native/workspace/context.rs`) and not run: the installed package ships the native module compiled, whose trace messages for this path are those of that source. A new context, and `refresh`, get their files through `acquire_files` (lines 195 to 295). A process that finds `nx_files.lock` in the workspace data folder held by another process's walk waits, up to `NX_WORKSPACE_WALK_WAIT_MS` (60 seconds by default), and takes the archive that walk writes, where it was written after the wait began; otherwise it walks under the lock itself and writes the archive (lines 419 to 449). The process that walked can have listed a folder before a file was written into it, so a context made after the write can still lack the file. `setupWorkspaceContext` passes only `watch` and `alwaysWatch`, neither of which turns this off. Processes that walk are an nx command's main process when it starts (`bin/nx.js`, line 130) and when it builds a graph without the daemon (`refreshWorkspaceContext`), the daemon when it starts (`daemon/server/server.js`, line 382) and after `resetInternalState`, which makes its watching context again at once, every task or batch process that makes a context, the checks of other tasks among them, and a plugin worker that finds no archive to load. An inspector initialised before a reset keeps the files it took and still answers; the context holds no other reader in a task's process.
2312
+ - **A batch process.** `tasks-runner/batch/run-batch.js` gets the project graph in its message and builds none, and nothing between two groups of the plugin's batch read the context again: the log showed one context made, by the first group's check, and only that check's and the later checks' reads. With two crates of one workspace whose `build` targets give each its own feature set, `nx run-many -t build` ran a group of one crate for each in one batch process; each build script wrote a file during its own build. Without a reset, the check of the group that ran second missed the file that its build had written into a folder its script names with `rerun-if-changed`, and failed for a file written into its crate's own folder that its library includes, which the crate's inputs cover. Two `build` groups of one workspace under `workspace-build`, of which the batch leaves the second for a following batch ([[DES-BATCH]]), and two groups of different workspaces, whose lockfile tasks finished at different times, each ran in a process of their own.
2313
+ - **A task run on its own.** `bin/run-executor.js` calls `run` of `command-line/run/run.js`, which reads the cached graph (`readCachedProjectGraph`, line 175) and makes no context. With `--batch=false`, the only context made in the task's process was made by the check, after cargo. `nx run <crate>:build` without that flag ran in a batch process.
2314
+ - **Cost.** The reset and the first glob after it took 2.8 to 5.7 ms, median 3.4 ms, over 20 runs in a copy of `batch-groups` after a build, whose 20 listed files leave its `target` out; 5.6 to 9.3 ms in this repository, 1048 files; and 21 to 43 ms with about 10,000 more files, where a glob on a kept context took about 3 ms. On 21 November 2026, for nxr-ffjvc9, a Node.js script loaded the installed Nx's `HashPlanInspector` and workspace context and timed three rounds of a reset, an inspector made and initialized, which builds the context, a second one, and a glob of every file from the built context. In this repository, 1,078 files and 7 projects, they took 10.5 to 14.4 ms, 1.4 to 1.6 ms and 0.8 to 0.9 ms; in a throwaway repository of 30,001 files and one project, 66 to 125 ms, 16 to 26 ms and 10 to 16 ms. A build of the plugin in which the checks of a group shared one inspector ran `build-input-check.spec.ts` (1 min 26 s, against 1 min 23 s and 1 min 35 s before), `napi-build.spec.ts` (57.1 s, against 58.6 s) and a batched build of three crates measured alone (1.77 s and 2.15 s, against 1.87 s) no faster than with an inspector per check, within the noise of a machine that other processes share.
2315
+ :::
2316
+
2317
+ :::mara evidence EVD-CARGO-PUBLISH-REGISTRIES
2318
+ :mid: 01M7DMCC1WD0BE0TJ7BB161T31
2319
+ :title: Which registry cargo publishes a crate to, and where it looks up the crate's path dependencies
2320
+ :status: accepted
2321
+ :supports: DES-RELEASE
2322
+ :supports: ADR-BATCHED-PUBLISH
2323
+ :supports: ADR-PUBLISH-REGISTRY-OPTION
2324
+ :supports: ADR-PUBLISH-REPLACED-CRATES-IO
2325
+
2326
+ Experiments on 14 November 2026 for nxr-fwxn1r, which repeated the cargo results of that issue's research, with cargo 1.100.0 (3acc79c0c 2026-11-05) and 1.91.0 (ea2d97820 2025-10-10) on Linux x86-64, `RUSTUP_AUTO_INSTALL=0`, a Cargo home per version and throwaway git repositories outside this repository with `Cargo.lock` committed. Every run was in a network namespace with only loopback, where a script served local sparse registries with a publish endpoint and logged each upload with its `Authorization` header and the registry that the upload gave each dependency. The Cargo homes named three of them `alpha`, `beta` and `cio`. Where a case says that crates.io is replaced, `--config` replaced it either through a `[source]` table, `cio-src`, with `cio`'s index, or with `replace-with = "cio"`, naming the registry itself, as the test harness's Cargo home does. Every call passed `--locked`, and the results were the same on both versions unless a version is named. No experiment passed `--registry crates-io`, and each run that went for crates.io failed to connect.
2327
+
2328
+ - **Which registry.** In `cargo publish --dry-run --no-verify --locked -p <crate>`, `--registry` won over `CARGO_REGISTRY_DEFAULT`, which won over `registry.default` in a configuration file. Either default won over a crate's `publish` list: where the list left it out, cargo failed with "`rs-pla` cannot be published. The registry `beta` is not listed in the `package.publish` value in Cargo.toml.", while the same call with `--registry alpha`, the list's entry, went to `alpha`. Without a default, a crate whose list has one entry went there, after "note: found `alpha` as only allowed registry. Publishing to it automatically."; a list with two entries failed with "--registry is required to disambiguate between "alpha" or "beta" registries", and went to the default where the list held it. With neither a default nor a list and crates.io replaced, cargo failed with "crates-io is replaced with non-remote-registry source registry `cio-src`; include `--registry crates-io` to use crates.io", or, where `replace-with` names the registry, "crates-io is replaced with remote registry cio; include `--registry cio` or `--registry crates-io`". An empty `CARGO_REGISTRY_DEFAULT` failed with "registry name cannot be empty", also beside a default in a file.
2329
+ - **Several crates.** `-p` for crates with `publish = ["alpha"]` and `["beta"]` failed with "conflicts between `package.publish` fields in the selected packages", and with `--registry alpha` with "`rs-plb` cannot be published. The registry `alpha` is not listed …". A crate without a list beside one with `["alpha"]` failed without a default with "--registry is required because not all `package.publish` settings agree". Each of these crates went through when called alone, and the crate without a list and the one with `["alpha"]` went through together under `registry.default = "alpha"` or with `--registry alpha`.
2330
+ - **Reading the choice.** `cargo config get registry.default` failed: "the `cargo config` command is unstable, and only available on the nightly channel of Cargo". A `registry.default` set only in a file that `.cargo/config.toml` adds with `include = ["extra.toml"]` sent the crate to `alpha` on 1.100, while 1.91 ignored the file and failed as without a default. `[source.crates-io] replace-with = "cio"` set only in such a file was applied by 1.100 and ignored by 1.91 in the same way. `CARGO_SOURCE_CRATES_IO_REPLACE_WITH=cio` in the environment replaced nothing: cargo went for crates.io's index.
2331
+ - **The first line.** Wherever cargo chose a registry, the first line of its output that starts with `Updating` named it, ``Updating `alpha` index``, before anything that failed later: also where packaging failed on a dependency missing from the registry, and on a committed bump beside a stale `Cargo.lock`, where 1.100 went on with "cannot update the lock file … because --locked was passed to prevent this" and 1.91 with "the lock file … needs to be updated but --locked was passed to prevent this". Where cargo could not choose, it failed before any such line. These dry runs uploaded nothing and left `git status` empty, also with the stale lockfile; they wrote the packaged crates into `target/package`, which `.gitignore` covered, and the second session below found that they overwrite files that the repository tracks there.
2332
+ - **Tokens.** `CARGO_REGISTRY_TOKEN` alone did not let cargo upload to `alpha`, whether `alpha` came from `--registry`, `CARGO_REGISTRY_DEFAULT`, `registry.default` in a file or a one-entry `publish` list: "no token found for `alpha`, please run `cargo login --registry alpha` or use environment variable CARGO_REGISTRIES_ALPHA_TOKEN". With `CARGO_REGISTRIES_ALPHA_TOKEN` the upload carried that token.
2333
+ - **URLs.** `--registry https://registry.npmjs.org/` failed with "invalid character `:` in registry name", a `sparse+` URL with "invalid character `+` in registry name", and `--index alpha` with "invalid url `alpha`: relative URL without a base". `--index` with an `http://` URL without `sparse+` made cargo fetch it as a git index, which failed. A real upload through `--index` with `beta`'s index URL failed with "command-line argument --index requires --token to be specified", although `CARGO_REGISTRIES_BETA_TOKEN` and `CARGO_REGISTRY_TOKEN` were set; its dry run succeeded. With `--token`, a crate with `publish = ["alpha"]` was uploaded to `beta` through `--index`, where 1.100 warned that `--index` ignores `package.publish` and that `--token` is deprecated, and 1.91 said nothing.
2334
+ - **Where dependencies resolve.** A workspace had `d-a`, `d-b` depending on it with `path` and `version`, and `d-c` with the same entry and `registry = "alpha"`. `cargo metadata --no-deps` gave the dependency of `d-b` `registry: null` and that of `d-c` `alpha`'s index URL, with `source: null` for both, and gave that URL also to a dependency inherited with `workspace = true` from a `[workspace.dependencies]` entry with `registry = "alpha"`. With `d-a` published to `alpha` and crates.io replaced by `cio-src`, `cargo publish --dry-run -p d-b --registry alpha` failed with "no matching package named `d-a` found" and "location searched: `cio-src` index (which is replacing registry `crates-io`)", and so did the same call with `CARGO_REGISTRY_DEFAULT=alpha` in place of `--registry`, and with `--no-verify`. `d-c` was uploaded to `alpha` with the dependency's registry `null`, the same registry, and to `beta` with `alpha`'s index URL.
2335
+ - **An unrelated crate.** With a `d-a` of the same version and other content uploaded to `cio`, `cargo info d-a@<version> --registry alpha --locked` exited with 0, "from registry `alpha`", and `cargo publish --locked -p d-b --registry alpha` exited with 0 and uploaded `d-b` to `alpha` with the dependency `["d-a", "^3.100.0", "https://github.com/rust-lang/crates.io-index"]`, `^3.91.0` on 1.91: `d-b` in `alpha` depends on crates.io's `d-a`. In the first round, 1.91's dry run of `d-b` did not fail as above but succeeded against such a crate, because the 1.100 round had left a `d-a` 3.100.0 in `cio` that `^3.91.0` accepts; with empty registries it failed as on 1.100.
2336
+ - **The harness's form.** Where `replace-with = "cio"` names the registry that the call publishes to, here through `CARGO_REGISTRY_DEFAULT=cio`, the dry run of `d-b` resolved `d-a` in `cio` and succeeded, and its output named `cio` for the call and again for the dependency. The crate that such a call uploads still names crates.io for the dependency, as the second session below found.
2337
+
2338
+ A second session the same day, after a review of the release design, used the same versions, namespace and kind of server, with crate names of each version's own, so that neither version's run could meet the other's crates.
2339
+
2340
+ - **What a published crate points to.** With `registry.default = "alpha"` and `[source.crates-io] replace-with = "alpha"` in a configuration file, `cargo publish --locked --registry alpha -p <a> -p <b>`, where `b` depends on `a` with `path` and `version` and no `registry` key, packaged `b` against the `a` of the same call, uploaded both to `alpha`, and gave `b`'s dependency the registry `https://github.com/rust-lang/crates.io-index` in the upload. With `registry = "alpha"` in the entry, the dependency's registry was `null`, the same registry. `cargo metadata --no-deps` gave an entry with `registry = "crates-io"` crates.io's index URL, and failed where a member's entry names a registry that no configuration names: "registry index was not found in any configuration: `zzz`".
2341
+ - **Looking a version up on crates.io.** In a workspace with `registry.default = "alpha"` in a file, whose member has the name and version looked up, `cargo info <name>@<version> --locked` described the member on 1.100, "version: 0.2.0 (from ./lk)", and asked `alpha` on 1.91. With `--index` and `cio`'s index URL, both asked `cio`. With `--index sparse+https://index.crates.io/`, and with `--index https://github.com/rust-lang/crates.io-index`, both asked what the configuration put in place of crates.io, the registry `cio` or the source `cio-src`, named it in the first line, ``Updating `cio` index``, and found the version there; without a replacement they printed `Updating crates.io index` and went for `index.crates.io`.
2342
+ - **crates.io as the target under a replacement.** With `replace-with = "cio"` and no default, the probe of a crate with `publish = ["crates-io"]`, and the probe of a crate without a list under `CARGO_REGISTRY_DEFAULT=crates-io`, printed `Updating crates.io index` and went for `index.crates.io`, as without the replacement.
2343
+ - **What publishing writes.** In a workspace that tracked files under `target/package` named like its crate's package, the probe overwrote tracked files: on 1.100 those under `target/package/tmp-crate` and `target/package/tmp-registry`, on 1.91 the one in `target/package` and the one under `tmp-registry`. A dry run with verification and a real `cargo publish` overwrote the same files. With `build.build-dir = "bdir"` in the workspace's configuration, the packaged crates went to `bdir/package` instead, also with `CARGO_TARGET_DIR` set, and a real publish wrote the unpacked sources under `bdir/package` and its verification build elsewhere under `bdir`, and nothing into `target`. With `CARGO_TARGET_DIR` and `CARGO_BUILD_BUILD_DIR` naming a folder outside the checkout, the probe wrote only there, `git status --ignored` stayed empty, and its output began with ``Updating `alpha` index`` as before.
2344
+ - **One workspace, three registries.** With crates.io replaced by `cio` and no default, the probe of a crate without a list failed with "crates-io is replaced with remote registry cio", while crates with `["alpha"]` and `["beta"]` went to their registries: one call with `--registry alpha` uploaded two `["alpha"]` crates, one depending on the other through an entry that names `alpha`, one with `--registry beta` the `["beta"]` crate, and the dry runs of both calls before them succeeded. Under `CARGO_REGISTRY_DEFAULT=alpha` the crate without a list and the `["alpha"]` crate went to `alpha` and the `["beta"]` crate was refused; with `registry.default = "beta"` in a file, the crate without a list went to `beta` and the `["alpha"]` crate was refused.
2345
+ - **cargo login.** With `registry.default = "alpha"`, `cargo login local-token` printed "Login token for `alpha` saved" and wrote `[registries.alpha]` into `credentials.toml`; without a default, it went for crates.io's index.
2346
+ - **The harness's form with registry keys.** With the variables that the test harness pins, `CARGO_REGISTRY_DEFAULT`, the registry's index, its token and the provider `cargo:token`, for a registry that also replaces crates.io, and with the dependency's entry naming that registry: after both crates' 0.1.0 were published and both bumped to 0.1.1, `cargo update --workspace` moved only the two members, the dry run of both with `--registry` succeeded although neither new version was in the registry, the real call uploaded the dependency first and gave the dependent's dependency the same registry (`null`), `cargo info <name>@0.1.1 --registry <name> --locked` found it, and `git status` stayed empty.
2347
+
2348
+ A third session the same day, after a second review, used the same versions, namespace and kind of server, crate names of each version's own, and Cargo homes or `--config` values that named or replaced the registries as each case says.
2349
+
2350
+ - **A named registry replaced.** With a `[source]` table holding `alpha`'s index and `replace-with = "beta"`, `alpha` having `a` 0.1.0 and `beta` an `a` 0.1.1: `cargo info a@0.1.1 --registry alpha --locked` printed ``Updating `beta` index`` and ``version: 0.1.1 (from registry `alpha-src`)``, the name of the table, and exited with 0; `a@0.1.0` gave "could not find `a@0.1.0` in registry `<alpha's index>`", naming `alpha`'s index although it had asked `beta`. With the replacement through a source `beta-src`, or with `--index` and `alpha`'s index in place of `--registry`, the first line named `beta-src` or `beta` in the same way. Where the replacement was a table named `alpha` holding `beta`'s index, the lookup printed ``Updating `alpha` index`` and still ``from registry `alpha-src` ``. `cargo publish --locked --registry alpha -p b`, `b` depending on `a` 0.1.1 through an entry that names `alpha`, printed ``Updating `alpha` index``, resolved `a` in `beta` and uploaded `b` to `alpha`, whose index had no 0.1.1, with the dependency in the same registry; the probe of `b` under `CARGO_REGISTRY_DEFAULT=alpha` printed ``Updating `alpha` index`` first as well.
2351
+ - **Two names for one index.** With `alias` configured in a file with `alpha`'s index beside `alpha`, every real upload to that index failed, also of a crate without dependencies: "multiple registries are configured with the same index url '<alpha's index>': alias, alpha"; the dry runs succeeded. With `alias` given only in the environment, `CARGO_REGISTRIES_ALIAS_INDEX`, uploads with `--registry alpha` succeeded and printed "Uploaded … to registry `alias`", a dependency whose entry names `alias` was recorded in the same registry (`null`), and lookups with `--registry alpha` and with `--registry alias` both printed ``Updating `alias` index`` and ``from registry `alias` ``. In both forms the probe of a crate with `publish = ["alpha"]` printed "found `alpha` as only allowed registry" and then ``Updating `alias` index``; with `alias` in the file, so did the probes of a crate with `["alpha", "beta"]` and of one without a list under `CARGO_REGISTRY_DEFAULT=alpha`. In both forms `--registry alias` for the crate with `["alpha"]` was refused before anything was uploaded, "The registry `alias` is not listed in the `package.publish` value", and `--registry alpha` went through. The report gave an entry with `registry = "alias"` `alpha`'s index.
2352
+ - **One name for two indexes.** With a Cargo home that names neither `alpha` nor `beta`, workspace `w1` configuring `shared` with `alpha`'s index and `w2` with `beta`'s: `d` of `w1` with `publish = ["shared"]` went to `alpha`; a copy of `d` of the same version was put into `beta`; `w2`'s report gave the entry of `e`, which depends on `d` by path and names `shared`, `beta`'s index; `cargo info d@0.1.0 --registry shared --locked` in `w2` printed ``Updating `shared` index`` and ``from registry `shared` `` and found the copy; and `e` went to `beta` with its dependency in the same registry, so that it depends on the copy, every line naming `shared`. With `CARGO_REGISTRIES_SHARED_INDEX` set to `alpha`'s index, `w2`'s report gave the entry `alpha`'s index, both workspaces' lookups asked `alpha`, and `d` and then `e` went to `alpha`, `e`'s dependency in the same registry.
2353
+ - **Offline.** With `CARGO_NET_OFFLINE=true`, or `net.offline = true` in a file, a lookup after an online one printed no `Updating` line and answered from the cache with exit code 0, on crates.io through its replacement as with `--registry alpha`. `CARGO_NET_OFFLINE=false` in the environment won over the file, and the line came back. Offline, the probe and a real `cargo publish` failed with "attempting to make an HTTP request, but --offline was specified".
2354
+
2355
+ A fourth session on 15 November 2026, for nxr-m8evx2, used the same two versions against the test harness's server, which served the registries `nx-rust-test`, `alpha` and `beta` on one port of the loopback interface, each under a path of its own, through a Cargo home that named all three, replaced crates.io with `nx-rust-test` and made the server its proxy, with each registry's index, token and the provider `cargo:token` also in the environment, and in throwaway git repositories outside this repository.
2356
+
2357
+ - **What cargo prints.** An upload printed ``Uploaded <name> v<version> to registry `<name>` `` on both versions. Every status line, ``Updating `<name>` index`` among them, went to standard error, and `cargo info` wrote the crate's description with ``version: <version> (from registry `<name>`)`` to standard output; it downloads a version that it finds, so a version that the index lists without a `.crate` file fails the lookup. For an entry with `registry = "alpha"`, also one inherited from `[workspace.dependencies]`, the report gave `alpha`'s index as the configuration spells it, `sparse+http://…/alpha/index/`, and for `registry = "crates-io"` `https://github.com/rust-lang/crates.io-index`. A crate with `publish = false` had `"publish": []`, one without the key `null`.
2358
+ - **A second name for one index.** With `CARGO_REGISTRIES_ALIAS_INDEX` set to `alpha`'s index, beside `alpha` in the Cargo home and in the environment, in the Cargo home alone or in the environment alone, before or after `alpha` among the variables, with `registry.default = "alpha"` or `[source.crates-io] replace-with = "alpha"` given with `--config`, with `alias` given with `--config` instead, and with a member whose entry names `alias`, the probe of a crate with `publish = ["alpha"]` and `cargo info --registry alpha` showed `alpha` in every line, ``Updating `alpha` index`` and ``from registry `alpha` ``: the display of `alias` that the third session saw did not appear. A real upload with `--registry alpha` failed with "multiple registries are configured with the same index url '<alpha's index>': alias, alpha" where both names came from the environment, and in the harness, where the Cargo home names `alpha`, with `alias` in the environment; so did an upload with `--registry shared` where a workspace's configuration gave `shared` `alpha`'s index. Which of two names cargo shows for one index therefore depends on the configuration in a way that these runs did not settle; the rule of **Registries** in [[DES-RELEASE]], which reads only what cargo shows, does not depend on it.
2359
+
2360
+ Not repeated: `cargo publish --registry crates-io` while crates.io is replaced, which the research for nxr-fwxn1r saw go for `index.crates.io` in its network namespace, because no experiment passes `--registry crates-io`. Not established: what cargo and crates.io do with a crate for crates.io whose dependency names another registry ([[RISK-REGISTRY-BEHAVIOUR]]), and a lookup that asks crates.io itself while the configuration replaces it.
2361
+ :::
2362
+
2363
+ :::mara evidence EVD-NX-24-PUBLISH-OPTIONS
2364
+ :mid: 01M7DMCC1WD0EPQSF9J0N6DEA8
2365
+ :title: What Nx 24.0.6 hands a publish task, and what @nx/js does with the registry option
2366
+ :status: accepted
2367
+ :supports: DES-RELEASE
2368
+ :supports: ADR-PUBLISH-REGISTRY-OPTION
2369
+
2370
+ The research for nxr-fwxn1r on 14 November 2026 read `nx` 24.0.6 and `@nx/js` 24.0.6, which this repository installs (paths under `dist/src/`), and ran a stand-in Nx workspace outside this repository with both linked from it, `NX_DAEMON=false` and a cache of its own. The stand-in executor had a batch implementation, `preferBatch: true` and a schema that declared `dryRun`, `registry` and `firstRelease`, and printed what it received. One project's `nx-release-publish` came from its `project.json` and another's from a stand-in plugin's `createNodesV2`, the shape that nx-rust's has. The lines named here were read again for this record; the runs were not repeated.
2371
+
2372
+ - **The flags.** `nx release publish` declares `--registry` and `--tag` as strings, `--access` with the choices `public` and `restricted`, and `--otp` as a number (`command-line/release/command-object.js`, lines 196 to 214). The combined `nx release` declares only `--otp` (line 94) and takes no unknown option (line 20): `nx release 0.2.0 --registry my-reg --dry-run` printed its help and "Unknown argument: registry".
2373
+ - **What a task receives.** `runPublishOnProjects` copies `registry`, `tag`, `otp`, `access`, `dryRun` and `firstRelease` into the overrides of every task of the run when the command has them, sets `NX_DRY_RUN=true` for a dry run, and adds `nxReleaseVersionData` under `nx release` (`command-line/release/publish.js`, lines 138 to 169). `nx release publish --registry https://registry.example.test/ --tag next --otp 123456 --access public --first-release --dry-run` gave both tasks of the batch the options `{"registry":"https://registry.example.test/","tag":"next","otp":123456,"access":"public","dryRun":true,"firstRelease":true}`, the same values among the overrides that the task graph holds for each task, and an empty `__overrides_unparsed__`: the raw string, the same for every project, and `otp` as a number. With `NX_BATCH_MODE=false` each task received the same. An unknown flag such as `--index sparse+http://x/`, also after `--`, reached every task as an option.
2374
+ - **Configuration.** A `registry` among a target's options in `project.json` reached the task, and `--registry` on the command line replaced it. A `targetDefaults` entry keyed by `nx-release-publish` with an npm URL in `options.registry` reached the target of the stand-in plugin, and an empty entry keyed by the stand-in's executor beside it kept it away, as [[EVD-NX-TARGET-DEFAULTS]] found for other targets. `release.groups.<group>.registry` was accepted and passed to no task. The `nx-release-publish` that Nx itself gives a package with `@nx/js` runs `@nx/js:release-publish` and takes the target defaults for that executor before those for the target name (`utils/package-json.js`, lines 145 to 163).
2375
+ - **@nx/js.** Its publish executor takes the registry from the package's `publishConfig`, else from the option `registry`, else from npm's configuration (`utils/npm-config.js`, lines 34 to 38), passes it as `--registry=<value>`, or `--<scope>:registry=<value>` for a scoped package, and passes `otp` and `access` as `--otp` and `--access` (`executors/release-publish/release-publish.impl.js`, lines 158 and 348 to 353), to the workspace's package manager. Offline, npm 12.2.1's `npm publish --dry-run --registry alpha` warned "Must be full url with "http://"" and published, as a dry run, to `https://registry.npmjs.org/`; pnpm 12.18.0 failed with "ERR_PNPM_PUBLISH_UNSUPPORTED_REGISTRY_PROTOCOL".
2376
+
2377
+ Not run: nx-rust's own target under `nx release publish` ([[RISK-NX-RELEASE]]), and yarn and bun.
2378
+ :::
2379
+
2380
+ :::mara evidence EVD-NX-24-PUBLISH-BATCHES
2381
+ :mid: 01M7FXG9X7C5B5336Q1GQW1KEK
2382
+ :title: How Nx 24.0.6 hands the nx-release-publish tasks of a release group to a batch
2383
+ :status: accepted
2384
+ :supports: DES-RELEASE
2385
+ :supports: ADR-BATCHED-PUBLISH
2386
+ :supports: RISK-NX-RELEASE
2387
+
2388
+ A run on 15 November 2026 for nxr-m8evx2, with `nx` 24.0.6, the version this repository installs, Node.js 26.12.0 and git 2.56.0 on Linux x86-64, in a throwaway Nx workspace outside this repository, with `NX_DAEMON=false`, a private `NX_CACHE_DIRECTORY`, `NX_NO_CLOUD=true`, and without `CI`, `GITHUB_ACTIONS` and the variables by which Nx detects an AI agent. A local plugin's `createNodesV2`, the shape that nx-rust's has, gave four projects `a`, `b`, `c` and `d` a target `nx-release-publish` that ran a local executor with an `implementation` and a `batchImplementation`, and gave each project `release.version.versionActions` naming a local module whose `readDependencies` reported `c → a` and `d → b`. `nx.json` put `a` and `b` into the independent release group `g1` and `c` and `d` into `g2`. The batch implementation logged the tasks, roots and options it received and `NX_DRY_RUN`, and reported each task successful from an async generator; the single implementation logged its task.
2389
+
2390
+ - **preferBatch.** Without `preferBatch` in the executor's entry in `executors.json`, `nx release publish` ran each task on its own. With `"preferBatch": true`, it printed "Running 2 tasks with probe-exec:publish" for each group and started one batch process with `a:nx-release-publish` and `b:nx-release-publish`, both roots, and then one with the tasks of `c` and `d`. With `g2` listed before `g1` in `nx.json`, the batches came in the same order: Nx runs the groups in the order of the dependencies that the version actions report, and calls `runTasksForCommand` once for each group (`command-line/release/publish.js`, lines 98 to 130 and 224), where the scheduler puts every runnable task of one executor with `preferBatch` into one batch (`tasks-runner/tasks-schedule.js`, lines 180 to 258).
2391
+ - **Options.** `nx release publish --dry-run --registry https://npm.example.test/ --otp 123456 --first-release` gave the same two batches, each task with the options `{"registry":"https://npm.example.test/","otp":123456,"dryRun":true,"firstRelease":true}`, and the batch process had `NX_DRY_RUN=true`.
2392
+ - **Filters.** `--projects=a,c` gave a batch of `a`'s task and then one of `c`'s, `--groups=g2` one batch of the tasks of `c` and `d`, and `--projects=c` a batch of that one task.
2393
+ - **Without batches.** With `NX_BATCH_MODE=false`, each of the four tasks ran on its own.
2394
+ - **nx release.** In a git repository with `release.git` set to commit and tag nothing and changelogs off, `nx release 0.2.0 --yes --first-release` gave the same two batches after versioning, each task with `firstRelease` and `nxReleaseVersionData`, which held each project's current and new version and its dependents.
2395
+
2396
+ The tests of [[VER-RELEASE]] then ran nx-rust's own target in the fixture `publish-crates`, with the same version of Nx. With `pub-base` alone in one release group and `pub-core` and `pub-tool`, which depend on it, in another, `nx release publish --projects pub-base` and `nx release publish --groups base` each ran the tasks of `pub-core` and `pub-tool` after that of `pub-base`, in a batch of their group: Nx's release graph adds the dependents of a selected project ([[EVD-NX-24-RELEASE]], "Dependents"), while `--groups` naming the dependents' group alone ran their tasks only. `nx run pub-base:nx-release-publish` ran that one task.
2397
+
2398
+ This settles the point of [[RISK-NX-RELEASE]] that was still unseen: under `nx release publish` and `nx release`, Nx hands the runnable `nx-release-publish` tasks of one release group to one batch when their executor has a batch implementation and sets `preferBatch`, as [[EVD-NX-24-BATCHES]] found for `nx run-many`, and a filter by project or group narrows the batch to the selected tasks of each group.
2399
+ :::
2400
+
2401
+ :::mara evidence EVD-CARGO-PUBLISH
2402
+ :mid: 01M7DBRA912K68NXEN2P6KCWMW
2403
+ :title: How Cargo reports, locks and publishes a workspace after a version bump
2404
+ :status: accepted
2405
+ :supports: DES-RELEASE
2406
+ :supports: ADR-BATCHED-PUBLISH
2407
+ :supports: ADR-RELEASE-DEPENDENTS
2408
+ :supports: RISK-REGISTRY-BEHAVIOUR
2409
+ :supports: RISK-UNCOMMITTED-PUBLISH
2410
+
2411
+ Experiments on 14 November 2026 with cargo 1.100.0 (3acc79c0c 2026-11-05) and 1.91.0 (ea2d97820 2025-10-10), and 1.89 where named, on Linux x86-64 with `RUSTUP_AUTO_INSTALL=0`, in throwaway git repositories outside this repository with a Cargo home of their own. Its `config.toml` replaced crates.io with a local sparse registry (`[source.crates-io] replace-with`), which `python3 -m http.server` served from a folder holding only an index, and named the same index as the registry `probe`. Nothing was uploaded anywhere. The first workspace had four members: `relprobe-a` and `relprobe-b`, which inherit `version.workspace = true` (0.1.0), `relprobe-b` depending on `relprobe-a` through `[workspace.dependencies] relprobe-a = { path = "a", version = "0.1.0" }` and on the registry crate `regdep = "1"`; `relprobe-c` (0.3.0), with a renamed optional dependency on `relprobe-a` with `version = "0.1.0"`, a build-dependency on it for `cfg(unix)` with `version = "0.1"` and a dev-dependency on `relprobe-b` without a version; and `relprobe-d` with `publish = false` and a path dependency on `relprobe-a` without a version. The second workspace had `relprobe-a` and `relprobe-b` inheriting 0.2.0, the second depending on the first through `[workspace.dependencies]` with `version = "0.2.0"`, all committed.
2412
+
2413
+ - **The report's dependencies.** `cargo metadata --no-deps --format-version 1` gave each dependency the fields `name`, the package name also for a renamed one, `rename`, `kind` (`null` for a normal dependency, `build`, `dev`), `optional`, `target` (`cfg(unix)`), `path` (absolute), `req`, `source`, `registry`, `features` and `uses_default_features`, on both versions. `req` is normalised: `version = "0.1.0"` gave `^0.1.0`, `"0.1"` gave `^0.1`, and a path dependency without `version` gave `*`. A dependency inherited with `workspace = true` looked like one written in the member's manifest, so the report does not say where a requirement is written. `publish = false` gave `publish: []`.
2414
+ - **An inherited version bumped alone.** With `[workspace.package].version` set to 0.2.0 and `[workspace.dependencies]` left at `version = "0.1.0"`, `cargo metadata` and `cargo update --workspace` failed on both versions with exit code 101: "failed to select a version for the requirement `relprobe-a = "^0.1.0"`", "candidate versions found which didn't match: 0.2.0", "required by package `relprobe-b v0.2.0`". `cargo metadata --no-deps`, with and without `--locked`, still succeeded. The project graph is then still created, while every cargo command that resolves the workspace fails, the lockfile task's among them.
2415
+ - **The lockfile after a bump.** With the requirements rewritten as well, in `[workspace.dependencies]` and in both entries of `relprobe-c`, and `regdep` 1.0.1 added to the index, `cargo update --workspace` printed "Updating relprobe-a v0.1.0 (…) -> v0.2.0" and the same for `relprobe-b`. In this fixture, where each package name is locked once, it changed only those two `version` lines of `Cargo.lock` and left `regdep` at 1.0.0, on both versions, and `cargo update --workspace --locked` passed afterwards; the second session below shows a lockfile in which more lines change. `cargo update -p relprobe-a` changed the same two lines.
2416
+ - **Several crates against one.** In the second workspace, with neither crate in the registry, `cargo publish --dry-run --registry probe -p relprobe-a -p relprobe-b` packaged and verified both and stopped before the upload with exit code 0 on both versions, also with `-p relprobe-b` first. `cargo publish --dry-run --registry probe -p relprobe-b` failed with exit code 101, "failed to prepare local package for uploading", "no matching package named `relprobe-a` found"; with `relprobe-a` 0.1.0 in the index it failed with "failed to select a version for the requirement `relprobe-a = "^0.2.0"`", "candidate versions found which didn't match: 0.1.0", while the multi-crate dry run still succeeded. `--no-verify` changed neither failure. Cargo 1.89 rejected several `-p` on `cargo publish`: "the `--package (multiple occurrences)` flag is unstable". Cargo 1.90 was not tried; it is older than the 1.91 that the plugin requires ([[ADR-COMPATIBILITY]]).
2417
+ - **Which registry.** With crates.io replaced, `cargo publish --dry-run` without `--registry` failed: "crates-io is replaced with non-remote-registry source registry `probe-src`". With `CARGO_REGISTRY_DEFAULT=probe` in place of `--registry`, the multi-crate dry run succeeded on both versions, so a test registry can be set up in a Cargo home alone.
2418
+
2419
+ The research for the release design measured these on the same day with the same two versions, against a local sparse registry with a publish endpoint to which it uploaded, and they were not repeated:
2420
+
2421
+ - **Uploads.** A multi-crate publish uploads in dependency order whatever the order of `-p`, and with `--workspace` skips crates with `publish = false`. A real multi-crate publish fails before uploading anything when a selected version already exists ("crate c@0.3.0 already exists"); a dry run only warns.
2422
+ - **Waiting.** With an index that showed an upload after 75 seconds, a single-crate publish waited 60 seconds, printed "timed out waiting" and exited with 0, and a multi-crate publish exited with 101: "unable to publish slowq … due to a timeout while waiting for published dependencies". `publish.timeout = 1` had no effect on 1.91.
2423
+ - **Flags.** `--token` is in the help of 1.91's `cargo publish` and no longer in 1.100's. Without `--allow-dirty`, a tree with uncommitted changes fails ("1 files in the working directory contain changes…").
2424
+ - **Dependencies when publishing.** A normal path dependency without `version` stops `cargo publish` ("all dependencies must have a version requirement specified when publishing"); a dev-dependency without `version` is left out of the published crate. In a cycle through a dev-dependency without `version`, cargo leaves it out and publishes both crates; with a `version`, the first publish is impossible, per crate and with `--workspace` ("no matching package named `cycx` found"). A path dependency is looked up on crates.io when packaged, also with `--registry` and `registry.default` set, unless its entry names a `registry`. A crate without `version` is reported as 0.0.0 with `publish = []`.
2425
+ - **The lockfile.** `cargo update -p a -p e`, and each form with `--offline` on a filled Cargo home, changed only the bumped members' lines; `--offline` fails with an empty Cargo home.
2426
+ - **cargo-release 1.1.7**, read: it treats crates that inherit the version as one version, writes it once, and rewrites requirements on a bumped crate over every member and the workspace root (`upgrade_dependency_req`).
2427
+ - **cargo-hakari 0.9.39**, read, not run: from dep-format-version 2 the hack crate's dependency is written as `workspace-hack = { version = "0.1", path = … }`, before that with `path` only. crates.io has a crate `workspace-hack` 0.1.0 of another author with no dependencies, to which such a requirement resolves there. cargo-hakari offers `cargo hakari publish -p <crate>`, which takes the dependency out, runs `cargo publish --allow-dirty`, puts it back and regenerates the lockfile, one crate per call, and a stub of the hack crate published once under a unique name, after which plain `cargo publish` works. A run of the same version, which found `hakari-package` in `.config/hakari.toml` naming the hack crate, is recorded in [[EVD-HAKARI-UNIFICATION]]. A run of the same version on 16 November 2026 confirmed the forms of the dependency and found `publish = false` in the hack crate that `cargo hakari init` writes ([[EVD-HAKARI-PUBLISHING]]).
2428
+
2429
+ A second session the same day, after a review of the release design, repeated each point below with cargo 1.100.0 and 1.91.0, in throwaway git repositories with a Cargo home per version. A script outside this repository served a local sparse registry with a publish endpoint, to which cargo uploaded for real; the Cargo home replaced crates.io with it and named it in `registry.default`. Nothing left the machine.
2430
+
2431
+ - **A dependent before its dependency.** With `a` 0.1.0 published, `a` and `b` bumped to 0.1.1 and `b` keeping the requirement `a = { path = "../a", version = "0.1.0" }`, which 0.1.1 still matches, the lockfile updated and everything committed, `cargo publish -p b` exited with 0: it compiled `a` 0.1.0 from the registry to verify `b`, uploaded `b` 0.1.1 with the requirement `^0.1.0`, and `a` 0.1.1 was never uploaded.
2432
+ - **Looking a version up.** `cargo info <name>@<version>` exited with 0 for a version that the registry has and with 101 and "could not find `<name>@<version>` in registry `<index URL>`" for a missing version or crate, with and without `--registry probe`, and with `--registry crates-io` under the replacement. A full version is matched exactly: with 0.1.0 and 0.1.2 in the registry, `@0.1.1` was not found, while `@0.1` gave 0.1.2, and `@=0.1.1` is an invalid package ID. Inside the workspace whose member is `a` 0.1.1, cargo 1.100 without `--registry` described the member ("version: 0.1.1 (from ./a)") and exited with 0, while 1.91 asked the registry; with `--registry` both asked the registry. With `--offline` and an empty Cargo home, a version that the registry has gave the same "could not find" message and 101; with the registry unreachable, cargo exited with 101 and "failed to load source for dependency" (1.100) or "download of config.json failed" (1.91). In a workspace whose `Cargo.lock` was stale, `cargo info … --registry probe` rewrote `Cargo.lock`; with `--locked` it left it unchanged and answered the same, 0 for a version present and 101 for one missing.
2433
+ - **Two cargo calls.** With `a` 0.2.0 in one workspace and `x` 0.2.0 in another depending on it by path with `version = "0.2.0"`, neither in the registry, `cargo publish --dry-run -p a` succeeded in the first and then `cargo publish --dry-run -p x` failed in the second: "failed to prepare local package for uploading", "no matching package named `…-a` found". For real, `cargo publish --locked -p a` returned once `a` was in the index, `cargo info a@0.2.0 --registry probe --locked`, started at once in the second workspace, exited with 0, and `cargo publish --locked -p x` uploaded `x` with the requirement `^0.2.0`.
2434
+ - **A stale lockfile.** A workspace whose binary crate `b` depends on `a` by path and on a registry crate locked at 1.0.0 while 1.0.1 was in the registry, with `a` and `b` bumped to 0.2.0, the requirement rewritten and committed without updating `Cargo.lock`: `cargo publish --dry-run -p a -p b` exited with 0 and left `Cargo.lock` modified. With `--locked`, the dry run and the real call failed, uploaded nothing and left the tree clean, 1.100 with "cannot update the lock file <path> because --locked was passed to prevent this" and 1.91 with "the lock file <path> needs to be updated but --locked was passed to prevent this". After `cargo update --workspace`, which kept the registry crate at 1.0.0, and a commit, `cargo publish --locked -p a -p b` succeeded as a dry run and for real, and the tree stayed clean.
2435
+ - **Uncommitted changes.** A changed source file, unstaged and then staged, made `cargo publish --dry-run --locked -p a` fail with "1 files in the working directory contain changes that were not yet committed into git" and the advice to pass `--allow-dirty`.
2436
+ - **Dependencies that are not published.** `b` depended on a member `int` with `{ path = "../int", version = "0.1.0" }`, where `int` had `publish = false`, and in a second workspace `publish = ["other-registry"]`. With no crate of that name in the registry, `cargo publish --dry-run --locked -p b` failed with "no matching package named `…-int` found". With an unrelated crate of that name and version published from another folder, `cargo publish --locked -p b` exited with 0 and uploaded `b` with the requirement `^0.1.0` on that crate.
2437
+ - **Requirements without a version.** `cargo metadata --no-deps` gave `req` `*` both for `{ path = "../a", version = "*" }` and for a path dependency without `version`. `cargo package` kept a dev-dependency with `version = "0.1.0"` in the packaged `Cargo.toml` and left out one with a path only. A real `cargo publish --locked -p b -p g`, where `g` has a normal path dependency without `version`, failed with "all dependencies must have a version requirement specified when publishing" and uploaded nothing, also not `b`.
2438
+ - **References in the lockfile.** With the member `n-a` 0.1.0 and the registry's `n-a` 0.1.0 both locked, because another member depends on `old-a = { package = "n-a", version = "=0.1.0" }`, the dependency lists name them `"n-a 0.1.0"` and `"n-a 0.1.0 (registry+…)"`. After `n-a` and the requirements on it were bumped to 0.2.0, `cargo update --workspace` changed the member's entry, rewrote each `"n-a 0.1.0"` that names the member to `"n-a 0.2.0"`, shortened the registry reference to `"n-a 0.1.0"`, which no longer needs its source, and left the registry's `n-a` at 0.1.0.
2439
+
2440
+ A third session the same day, while the test harness's registry was built (nxr-52c1bx), used cargo 1.100.0 and 1.91.0 against that registry: a Node server on 127.0.0.1 with the sparse protocol and the publish endpoint, which a Cargo home of its own named `nx-rust-test`, put in place of crates.io with `replace-with` naming the registry itself, made `registry.default` and made its HTTP proxy (`http.proxy`). Nothing left the machine.
2441
+
2442
+ - **Leaving the replacement.** `cargo publish --dry-run --registry crates-io` does not follow source replacement: on both versions it asked the proxy for a tunnel to `index.crates.io:443`, which the proxy refused, and failed with "CONNECT tunnel failed, response 403". `--index sparse+https://registry.invalid/` did the same for that host. With `no_proxy` or `NO_PROXY` set to `*` in the environment, cargo bypassed `http.proxy` and failed to resolve `registry.invalid` itself. Requests for the registry went through the proxy as well, by their whole URL.
2443
+ - **What cargo sends.** The upload carried the token as the whole `Authorization` header, and no index read or download carried one. Cargo described a path dependency with `version = "0.1.0"` with `version_req` `^0.1.0`, `kind` `normal` and `registry` `https://github.com/rust-lang/crates.io-index`, crates.io's index URL, although the crate was published to the registry that replaced crates.io. A token in `CARGO_REGISTRY_TOKEN` did not apply to that registry: cargo asked for `cargo login --registry nx-rust-test` or `CARGO_REGISTRIES_NX_RUST_TEST_TOKEN`.
2444
+ - **Refusals.** Where the index listed the version, cargo failed with "crate rega@0.1.0 already exists on `nx-rust-test` index" before any upload. Where the registry refused an upload with status 400 and crates.io's message, cargo failed with "the remote server responded with an error (status 400 Bad Request): crate version `0.1.0` is already uploaded", and a refusal of the token with status 403 in the same form.
2445
+ - **Waiting.** With an index that showed each upload 3 seconds late, `cargo publish -p rega -p regb` took about 6 seconds and published both. With `RUSTC_BOOTSTRAP=1`, `CARGO_UNSTABLE_PUBLISH_TIMEOUT=true` and `CARGO_PUBLISH_TIMEOUT=2`, which enable the unstable `publish.timeout` on a stable cargo, and an index that never showed the upload, cargo waited 2 seconds, warned "timed out waiting for rega v0.1.0 to be available" and failed with "unable to publish regb v0.1.0 due to a timeout while waiting for published dependencies to be available", as after the 60 seconds above.
2446
+ - **Configuration above the working folder.** After a review of the harness the same day, a listener of the test's own on the loopback interface stood in for another host. A `.cargo/config.toml` in a folder above the working folder took precedence over the Cargo home: with `[http] proxy = ""` there, cargo sent `GET /config.json` straight to the listener. Environment variables took precedence over that file: `CARGO_HTTP_PROXY`, `CARGO_NET_OFFLINE`, `CARGO_REGISTRY_DEFAULT` and the registry's `CARGO_REGISTRIES_NX_RUST_TEST_INDEX`, `_TOKEN` and `_CREDENTIAL_PROVIDER` each overrode its value. With the index from the environment, cargo no longer took the token from the Cargo home's `credentials.toml` and failed with "no token found". A global credential provider named in that file ran although the token was in the environment, unless the registry's own credential provider or the global list was set in the environment; for another registry, `cargo login` asked the registry first, which the proxy refused, and ran no provider. `CARGO_SOURCE_CRATES_IO_REPLACE_WITH` replaced nothing, also without such a file: cargo takes no source replacement from the environment.
2447
+ - **Git and SSH.** With the proxy in place, cargo's own git library connected to the listener for `git://` and `ssh://` URLs, of an index given with `--index`, of a git dependency and of `cargo install --git`, while `http://` and `https://` git URLs went through the proxy. With `net.git-fetch-with-cli`, the git command line connected for every scheme, ignoring cargo's proxy. With both it and `GIT_ALLOW_PROTOCOL=file`, git refused with "transport 'git' not allowed", and likewise for `ssh` and `https`, before it connected, also with `git-fetch-with-cli = false` in a configuration file above the working folder and with `insteadOf` rules that rewrote URLs to `git://` and `ssh://`, while a `file://` git dependency resolved. `GIT_ALLOW_PROTOCOL` without the command line changed nothing, and `GIT_SSH_COMMAND` beside both changed nothing.
2448
+
2449
+ A fourth session on 15 November 2026, while the publish target was built (nxr-m8evx2), ran the plugin's executor against the harness registry with cargo 1.100.0 and 1.91.0, and `cargo package --no-verify` in throwaway git repositories with a Cargo home of their own, offline.
2450
+
2451
+ - **Uncommitted changes in a subfolder.** In the fixture `publish-crates`, whose Cargo workspaces lie in the folders `rust` and `tools` of the git repository, an unstaged change to `rust/crates/base/src/lib.rs` made `cargo publish --locked --registry nx-rust-test -p pub-base` fail on 1.100 with "1 files in the working directory contain changes that were not yet committed into git", while 1.91 packaged, verified and uploaded the crate with the change. `cargo package --no-verify` behaved the same: in a repository whose workspace root is the folder `rust`, 1.91 packaged the changed crate, and in one whose workspace root is the repository root, it refused as 1.100 did. 1.97.1, 1.98.1 and 1.99.0 refused in the first layout too; 1.92 to 1.96 were not tried. So on 1.91, cargo's refusal of uncommitted changes, on which publishing relies (**Credentials and tree** in [[DES-RELEASE]]), does not hold for a crate of a Cargo workspace below the repository root (nxr-rsaxx7).
2452
+
2453
+ Not established: what crates.io itself checks on upload and how long its index takes ([[RISK-REGISTRY-BEHAVIOUR]]).
2454
+ :::
2455
+
2456
+ :::mara evidence EVD-CARGO-PATCH-AFTER-BUMP
2457
+ :mid: 01M7DP39E02408304AK7NARRH7
2458
+ :title: What Cargo makes of [patch], [replace] and profile entries that name a member after its version changes
2459
+ :status: accepted
2460
+ :supports: DES-RELEASE
2461
+
2462
+ Experiments on 14 November 2026 with cargo 1.100.0 and 1.91.0 on Linux x86-64, with `RUSTUP_AUTO_INSTALL=0`, in a throwaway folder outside this repository with a Cargo home of its own, whose `config.toml` replaced crates.io with a directory source that held `base` 0.1.0 as a stand-in for the registry. The workspace had the members `base` 0.1.0 and `user`, which asked the registry for `base = "0.1"`. Each case ran `cargo metadata --format-version 1 --offline` before and after the member `base` was bumped to 0.2.0, and `cargo tree -p user` where it shows which `base` cargo took. Both versions behaved alike, apart from the wording of one message.
2463
+
2464
+ - **`[patch]` with a version.** With `[patch.crates-io] base = { path = "crates/base", version = "=0.1.0" }` in the root manifest, and the same entry in `.cargo/config.toml` of the workspace folder, cargo took the member before the bump, and failed with exit code 101 after it: 1.100 with "patch `base` version mismatch", "patch location contains version `0.2.0`, but patch definition requires `=0.1.0`", 1.91 with "failed to resolve patches for `https://github.com/rust-lang/crates.io-index`". With the entry's requirement rewritten to `=0.2.0`, it succeeded again. A path in the configuration file was resolved against the folder above `.cargo`.
2465
+ - **`[patch]` without a version.** With `[patch.crates-io] base = { path = "crates/base" }`, `user` used the member before the bump, and after it `cargo metadata` succeeded and `cargo tree` showed `user` on the registry's `base` 0.1.0: cargo dropped the redirection without an error, because the member's new version no longer matched the requirement `0.1`. With `user`'s requirement rewritten to `0.2.0`, cargo took the member again, although the registry had no 0.2.0.
2466
+ - **`[replace]`.** With `[replace] "base:0.1.0" = { path = "crates/base" }` and no `[patch]`, which cargo refuses beside `[replace]` in one manifest ("cannot specify both [replace] and [patch]"), cargo took the member before the bump and failed after it: "no matching package for override `https://github.com/rust-lang/crates.io-index#base@0.1.0` found", "version required: =0.1.0". With the key rewritten to `base:0.2.0`, it succeeded with "package replacement is not used", and `user` was left on the registry's 0.1.0.
2467
+ - **A profile's package table.** With `[profile.dev.package."base:0.1.0"] opt-level = 2` and `user` depending on the member by path, `cargo metadata` succeeded after the bump and `cargo build` warned "profile package spec `base@0.1.0` in profile `dev` has a version or URL that does not match any of the packages": the profile's settings no longer applied to the member.
2468
+
2469
+ A second session the same day, in the same way, with a registry `private` whose sparse index `sparse+https://example.invalid/` the workspace's `.cargo/config.toml` named in `[registries.private]`, and `user` asking it for `base = { version = "0.1", registry = "private" }`:
2470
+
2471
+ - **Keys of `[patch]` for a registry.** `cargo metadata --offline` resolved `user`'s `base` to the member through `[patch.private]`, through `[patch."sparse+https://example.invalid/"]`, and through `[patch.private]` also where the dependency named the registry by `registry-index = "sparse+https://example.invalid/"`. With `[patch."https://example.invalid/"]`, the index URL without `sparse+`, cargo applied no patch and failed: "no matching package named `base` found". So for a sparse registry the key has to keep `sparse+`.
2472
+ - **Specifications in a profile's package table.** With `user` depending on the member by path, `cargo build` warned of no unmatched specification before the bump and warned "profile package spec … has a version or URL that does not match any of the packages" after it for each of `base@0.1.0`, `base:0.1.0`, `base@0.1`, `path+file://<folder>#base@0.1.0`, `path+file://<folder>#0.1.0`, `file://<folder>#base@0.1.0` and `file://<folder>#0.1.0`, where `<folder>` was the member's folder; `path+file://<folder>#base` and `file://<folder>`, without a version, matched before and after.
2473
+ :::
2474
+
2475
+ :::mara evidence EVD-CARGO-LOCKFILE-UPDATE
2476
+ :mid: 01M7DYSVZ3E0N3ADZZKQJNDK6Z
2477
+ :title: Which lockfiles a version bump makes stale, what the lockfile step of nx release version leaves, and which files cargo cannot read
2478
+ :status: accepted
2479
+ :supports: DES-RELEASE
2480
+
2481
+ Experiments on 14 November 2026 with cargo 1.100.0 and 1.91.0, with `RUSTUP_AUTO_INSTALL=0` and a Cargo home of their own, on copies of the fixture `release-crates`, and runs of the plugin's lockfile step through Nx 24.0.6 in the tests of group 4 of [[VER-RELEASE]], each against a harness registry of its own that stood in for crates.io.
2482
+
2483
+ - **A lockfile outside the changed workspaces.** With `xtask` in `tools/` depending on `base` in `rust/` by path without a version requirement, `tools/` kept its manifests when `base` went from 0.1.0 to 0.2.0, while its `Cargo.lock` still locked `base` 0.1.0: `cargo metadata --locked` there failed with exit code 101 on both versions, 1.100 with "cannot update the lock file … because --locked was passed to prevent this", 1.91 with "the lock file … needs to be updated but --locked was passed to prevent this". `cargo update --workspace` there printed "Updating base v0.1.0 (…) -> v0.2.0" and changed only that version line. A lockfile names no path for a path package, only its name and version.
2484
+ - **A workspace without a lockfile.** `cargo update --workspace` in `tools/` without a `Cargo.lock` exited with 0 on both versions and wrote one, as every resolving cargo command does.
2485
+ - **The step through Nx.** After `nx release version 0.2.0 --projects base`, in a lockfile that locked the member `base` and a registry crate `base` 0.1.0, the member's entry and every reference to it moved to 0.2.0 and the dependents' entries to their new versions, cargo shortened the reference to the registry crate to `base 0.1.0`, which the name and version alone no longer make ambiguous, and `regdep` stayed at 1.0.0 although the registry had 1.0.1; `cargo update --workspace --locked` passed afterwards in both workspaces, and Nx's release commit held both lockfiles. With the plugin's `locked` option and with `NX_RUST_LOCKED=true`, the step ran `cargo update --workspace` without `--locked`.
2486
+ - **Failures.** With the registry stopped and an empty Cargo home, `cargo update --workspace` in the workspace that asked the registry retried three times ("spurious network error … Could not connect to server") and failed with exit code 101, "failed to get `regdep` as a dependency of package …", "unable to update registry `crates-io`"; with `CARGO_NET_OFFLINE=true` and an empty Cargo home it failed with "no matching package named `regdep` found" and "offline mode (via `--offline`) can sometimes cause surprising resolution failures". Where that was the second of two workspaces, the first lockfile was updated, the manifests were written, nothing was staged, and Nx made no commit or tag; `git checkout --` with the files that the message listed restored a clean tree.
2487
+ - **Ignored files.** Nx's `gitAdd`, through which it stages and commits, leaves out each file that `git check-ignore` reports (`command-line/release/utils/git.js`, lines 243 to 281 and 297 to 303), so a lockfile that git ignores and that the step returned would not be staged either.
2488
+ - **A linked lockfile.** With `tools/Cargo.lock` a symbolic link to `locks/tools.lock` in the same repository, the step's `cargo update --workspace` in `tools/` wrote the new lockfile into `locks/tools.lock` and left the link as it was, on both versions, and `cargo update --workspace --locked` passed there afterwards; the link's path stayed unchanged for git.
2489
+ - **Files that cannot be read.** In a single-crate workspace with a `.cargo/config.toml`, `cargo metadata --no-deps` exited with 0 on both versions while the `.cargo` folder had mode 000, so that cargo could not look into it, and read no configuration from it; with the folder searchable and the file at mode 000, it failed with exit code 101, "could not load Cargo configuration". A lockfile that cannot be read, as `tools/Cargo.lock` at mode 200, says nothing about whether the run makes it stale.
2490
+ :::
2491
+
2492
+ :::mara evidence EVD-NX-24-RELEASE
2493
+ :mid: 01M7DBRA91S2P3MB401BJTKKH1
2494
+ :title: What Nx 24.0.6 release asks of a plugin and does with its version actions and publish target
2495
+ :status: accepted
2496
+ :supports: DES-RELEASE
2497
+ :supports: ADR-BATCHED-PUBLISH
2498
+ :supports: ADR-RELEASE-DEPENDENTS
2499
+ :supports: RISK-NX-RELEASE
2500
+
2501
+ A reading, not a run, of the `nx` 24.0.6 package that this repository installs (paths under `dist/src/`), on 14 November 2026: by the research for the release design, and again for the lines named here. The research also read `@nx/js` 24.0.6, a devDependency of this repository that is installed with it, and the published tarball of `@monodon/rust` 3.0.0. This item said until 14 November 2026 that `@nx/js` was not installed here; that was wrong, and none of the facts below rested on it ([[EVD-NX-24-PUBLISH-OPTIONS]] reads it again).
2502
+
2503
+ - **The interface.** A plugin's version actions extend `VersionActions` (`command-line/release/version/version-actions.d.ts`) and write `validManifestFilenames`, `readCurrentVersionFromSourceManifest`, `readCurrentVersionFromRegistry`, `readCurrentVersionOfDependency`, `updateProjectVersion` and `updateProjectDependencies`; they may override `readDependencies`, `calculateNewVersion`, `init` and `validate`. `excludeManifestsFromFormatting` is `false` unless they set it (`version-actions.js`, line 96). The module may export `afterAllProjectsVersioned(cwd, { dryRun })`, which Nx calls once per module after it has written its changes and whose returned files it stages (`version-actions.js`, lines 50 to 81; `version.js`, line 190).
2504
+ - **Registration.** A project's `release.version` may carry `versionActions` (`config/workspace-json-project-json.d.ts`, line 102), which wins over the release group's setting, so a plugin can give it to the projects it creates, as `@monodon/rust` does; the group's default is `@nx/js/src/release/version-actions`.
2505
+ - **Dependents.** The release graph takes each project's dependencies only from `readDependencies` (`utils/release-graph.js`, lines 212 to 220), and orders release groups and the projects in a group by them (`topologicallySortReleaseGroups` and `topologicallySortProjects`, lines 483 to 505). The default `readDependencies` leaves out `implicit` edges: "Skip implicit dependencies for now to match legacy versioning behavior" (`version-actions.js`, lines 215 to 219). Under `updateDependents`, whose default is `always` (`release-group-processor.js`, line 616), a dependent gets a patch bump "because a dependency was bumped". Requirements are updated only for dependents that are configured for release. A run showed one exception: a fixed group without a bump of its own is bumped through the project graph's edges, `implicit` ones included ([[EVD-NX-24-VERSION-ACTIONS]]).
2506
+ - **Order.** `validate` runs before the bumps; Nx writes the changed files after it has processed every project, formats them except the manifests that version actions exclude (`version.js`, line 182), calls `afterAllProjectsVersioned`, and then commits and tags.
2507
+ - **Defaults.** `currentVersionResolver` is `disk` (`utils/release-graph.js`, lines 575 to 577), `preserveMatchingDependencyRanges` is `true`, as it has been since Nx 22 (lines 603 to 609), and `adjustSemverBumpsForZeroMajorVersion` is `true`, which matches Cargo's caret rule for 0.x versions. `@nx/js` keeps a range that the new version satisfies and fails on one that it leaves.
2508
+ - **Publishing.** `nx release publish` runs the target named `nx-release-publish` and no other (`command-line/release/publish.js`, line 170), one release group after another in the order of the release graph, over every project of a group, bumped or not (lines 98 to 130). It passes `nxIgnoreCycles: true`, and with `--projects` or `--groups` it excludes task dependencies (lines 89 to 91). As overrides it passes `registry`, `tag`, `otp`, `access`, `dryRun`, which also sets `NX_DRY_RUN=true`, and `firstRelease` when they are given, and `nxReleaseVersionData` from `nx release` (lines 139 to 168). The research found that Nx breaks a task cycle in an arbitrary direction (`tasks-runner/run-command.js`, `task-graph-utils.js`) and that `@nx/js`'s publish executor skips versions that the registry already has.
2509
+ - **Commit and tag.** `nx release version` defaults to `commit: false`, `tag: false` and `stageChanges: true` (`command-line/release/config/config.js`, lines 106 to 120), and commits only where its git settings ask for it (`version.js`, line 263). A root `release.git` is merged into those settings (`config.js`, lines 346 to 355), but `nx release version` refuses it and stops unless `--git-commit`, `--git-tag` and `--stage-changes` are all given (`version.js`, lines 66 to 80; [[EVD-NX-24-VERSION-ACTIONS]]). The combined `nx release` commits and tags unless `release.git` says otherwise (`release.js`, lines 74 to 76), refuses granular `release.version.git` and `release.changelog.git` (lines 36 to 47), and publishes after asking, or at once with `--yes` (lines 261 to 266).
2510
+ - **Batches.** A publish task joins a batch as any task does: its executor has a batch implementation and sets `preferBatch` (`tasks-runner/tasks-schedule.js`, lines 219 to 232), and `NX_BATCH_MODE=false` turns batching off (line 119). `nx release publish` has no `--batch` flag.
2511
+ - **@monodon/rust 3.0.0.** It sets `release.version.versionActions` and a target `nx-release-publish` with `dependsOn: ["^nx-release-publish"]` on each crate whose `publish` is not `[]`, with `static` edges from all dependencies. It reads `[package].version` only and throws "Ensure [package].version is set" for an inherited version, never reads a registry, and finds a dependency by its Nx project name in `dependencies` and `dev-dependencies` only, missing build-dependencies, `[target.*]` tables, renamed dependencies, `workspace = true` and Nx names that differ from the crate's. It writes manifests through `@ltd/j-toml`, which keeps comments and reformats the file; runs `cargo update --workspace` in the Nx root only, swallows its failure and skips it in a dry run; and publishes with `cargo publish --allow-dirty -p <crate>`, one crate per task.
2512
+
2513
+ A run of version actions that a plugin's `createNodes` gives its projects is recorded in [[EVD-NX-24-VERSION-ACTIONS]], and a run of a publish target whose executor sets `preferBatch`, which showed that Nx hands the publish tasks of a group to one batch, in [[EVD-NX-24-PUBLISH-BATCHES]].
2514
+ :::
2515
+
2516
+ :::mara evidence EVD-NX-24-VERSION-ACTIONS
2517
+ :mid: 01M7DHY1AFJ7VWPDWR1P80GTR2
2518
+ :title: What Nx 24.0.6 does at run time with version actions that a plugin gives its projects
2519
+ :status: accepted
2520
+ :supports: DES-RELEASE
2521
+ :supports: RISK-NX-RELEASE
2522
+ :supports: ADR-RELEASE-DEPENDENTS
2523
+
2524
+ A run, on 14 November 2026, of `nx` 24.0.6, the version this repository installs, with Node.js 26.12.0, git 2.56.0, cargo 1.100.0 and oxfmt 0.78.0 on Linux x86-64, in a throwaway git repository outside this repository, with the Nx daemon off; paths under `dist/src/command-line/release/` name the lines read beside it. A local plugin stood in for nx-rust: it made a project of each crate of one Cargo workspace, `a` 0.1.0, `b` 0.1.0 with a normal dependency on `a` that carries a version requirement, and `c` 0.3.0 with a dev-dependency on `a`, set `release.version.versionActions` on each to a local module, and returned the edges `b → a` and `c → a`, both `implicit`, as nx-rust does ([[DES-PROJECT-GRAPH]]). The module extended Nx's `VersionActions`, logged each call and reported from `readDependencies` only `b → a`, which is what the manifests give under [[ADR-RELEASE-DEPENDENTS]]. The repository root had an oxfmt configuration.
2525
+
2526
+ - **Registration.** Nx took the `versionActions` that the plugin's `createNodes` gave each project: it loaded the module once, constructed its class for every project configured for release and called `init` on each.
2527
+ - **Order of calls.** `nx release version 0.2.0 --projects a`, with the three crates in one independent group, called `init` for every configured project; `readDependencies` for every configured project, `c` too, which the run did not version; `readCurrentVersionFromSourceManifest` for the projects of the run; `readCurrentVersionOfDependency` for the dependents that `readDependencies` gave; `validate` for each project of the run; `calculateNewVersion` and `updateProjectVersion` for `a` and then for `b`; `updateProjectDependencies` for `a`, and for `b` with `{ "a": "0.2.0" }`; and last `afterAllProjectsVersioned`.
2528
+ - **Dependents.** In that run `b` got a patch bump "because a dependency was bumped" and `c` none. For the dependents of a bumped project and for the order of release groups and of the projects in a group, Nx used only what `readDependencies` reported. Its default `readDependencies` reports nothing here, because both edges are `implicit` (`version/version-actions.js`, lines 215 to 220).
2529
+ - **A fixed group without a bump of its own.** With `a` and `b` in an independent group `core` and `c` alone in a fixed group `apps`, both with version plans, and a plan for `a` only, `nx release version` gave `c` 0.3.1 "because a dependency project belonging to another release group was bumped". For a fixed group that gets no bump of its own, Nx reads the project graph's dependencies of each of its projects, `implicit` ones included, and bumps the whole group when one of them lies in a group that it has already processed and bumped (`version/release-group-processor.js`, lines 236 to 263). With `apps` listed before `core` in `nx.json`, which the reported dependencies leave free to come first, `c` got no bump. Nx also hands `updateProjectDependencies` the graph's dependencies of a project, `implicit` ones included, without each one for which `readCurrentVersionOfDependency` reports no version (lines 486 to 520).
2530
+ - **Dependents of a fixed group.** With `a` alone in a fixed group `core` and `b` and `c` in an independent group `apps`, both with version plans, and a plan for `core` only, `nx release version` bumped `a` and left `b` as it was, although `readDependencies` reported `b → a`: Nx bumps the dependents of a project only where it bumps that project on its own, as in an independent group, and not where it bumps a fixed group as a whole (lines 236 to 341).
2531
+ - **Two versions for one crate.** Rerun on the same day with the plugin's own version actions, on a copy of the fixture `release-crates`, where `core` also depended on `base` through `[workspace.dependencies]`; each line that the version actions print for a write counted one call of `updateProjectVersion`. With `base` alone in a fixed group and `normal-user`, which depends on it, in an independent group, `nx release version 0.2.0 --groups core` wrote `base` once and `normal-user` once, with 0.2.0 "from the given specifier": Nx added it as a dependent, gave it no bump for its dependency in the fixed group and then the specifier, also with `dev-user` beside it in the group, in either order. With `base` and `normal-user` in one independent group, the same command wrote `normal-user` twice, first 0.1.1 "because a dependency was bumped" and then 0.2.0 "from the given specifier", which stayed; this is the configuration of the run that the first version of this item attributed to the layout above. With `base` in an independent group and `core` and `api`, which inherit one version, in a fixed group, `nx release version 0.2.0 --groups first`, and also `nx release version` with version plans `base: minor` and `crates: major`, wrote `core` and `api` twice each: 0.1.1 as dependents, `api` as `core`'s, and then the group's 0.2.0, which stayed. So a crate of a fixed group, too, can get two versions in one run.
2532
+ - **Hooks for what Nx decides across groups.** Nx bumps a fixed group without a bump of its own through `bumpVersionForProject` with the reason `DEPENDENCY_ACROSS_GROUPS_WAS_BUMPED` for each of its projects with such an edge (line 262), which calls the project's `calculateNewVersion` with that reason and then its `updateProjectVersion` (lines 584 to 596). It judges whether a group was bumped by the first of its projects in the run (`getFixedReleaseGroupBumpType`, lines 647 to 664). It calls `updateProjectDependencies` for no project before it has decided every version of the run: `updateDependenciesForProject` defers each call until `finalizeAllVersionDecisions`, which runs after the last group and then makes the deferred calls (lines 138, 486 to 495 and 533 to 545); every project whose version a run writes gets one.
2533
+ - **Failures.** A throw in `validate`, in `updateProjectVersion` or in `updateProjectDependencies` made the command exit with 1 and left every file as it was, without a commit or tag: Nx keeps the changes in its tree and writes them once every group is processed (`version.js`, lines 155 to 189). A throw in `afterAllProjectsVersioned` exited with 1 after the manifests were written, and left them changed and unstaged, without a commit or tag. Nx replaces an error that `readCurrentVersionFromSourceManifest` throws with its own message, "The project … does not have a Cargo.toml file available in …", and an error or `null` from `readCurrentVersionFromRegistry` with "Unable to resolve the current version from the registry. Please ensure that the package exists in the registry …", or with the version on disk where `fallbackCurrentVersionResolver` is `disk` (`version/resolve-current-version.js`, lines 34 to 54 and 57 to 122).
2534
+ - **After the writes.** `afterAllProjectsVersioned` ran once, after the new versions were on disk and before the commit, and returned files that Nx would stage. With `release.version.git` set to `{ "commit": true, "tag": true }`, Nx then committed and tagged `a@0.2.0` and `b@0.1.1`. Under `nx release 0.2.0 --projects a --skip-publish --first-release`, with `release.git` set to the same, it ran before Nx staged, committed and tagged. With `--dry-run` it ran with `dryRun: true`, and Nx wrote nothing.
2535
+ - **Root `release.git`.** With `release.git` in `nx.json`, `nx release version` stopped with exit code 1 before it read any version: "The "release.git" property in nx.json may not be used with the "nx release version" subcommand or programmatic API. Instead, configure git options for subcommands directly with "release.version.git" and "release.changelog.git"." With `--git-commit --git-tag --stage-changes` it ran, committed and tagged: the check passes only when all three are given (`version.js`, lines 66 to 80). `nx release` refuses `release.version.git` in turn ([[EVD-NX-24-RELEASE]]).
2536
+ - **Formatting.** Nx formats the files that a run changed with the repository's formatter, here oxfmt, which formats TOML, apart from the manifests in the `manifestsToUpdate` of version actions that set `excludeManifestsFromFormatting` (`version.js`, lines 180 to 187). An edit to `rust/Cargo.toml`, which no `manifestsToUpdate` held, was formatted back, while after the module had added that path to its `manifestsToUpdate` in `init` the edit stayed byte for byte. Nx reads `manifestsToUpdate` only there and in the default `validate`, which checks that each file exists.
2537
+ - **Symbolic links.** Rerun on the same day in the tests of groups 3 and 4 of [[VER-RELEASE]], on copies of `release-crates` in which `normal-user`'s `Cargo.toml` and `rust/.cargo/config.toml` were symbolic links to files in another folder of the repository, and in which `tools/Cargo.lock` was one: with the version actions writing through the links' paths and `afterAllProjectsVersioned` returning the lockfile's, Nx wrote the new versions into the files that the links lead to and staged and committed the links' paths, which git saw unchanged, so the commit left out the three changed files and the tree stayed dirty. Nx stages the paths that its tree changed and those that `afterAllProjectsVersioned` returns, as they are (`version.js`, lines 250 to 252), and leaves a file out of formatting only by the path in `manifestsToUpdate`: oxfmt reformatted the linked manifest where `manifestsToUpdate` named it by the link. Nx's tree answers `null` from `read` for every file that it cannot read, a missing one and one without read permission alike (`generators/tree.js`, lines 26 to 44).
2538
+
2539
+ This answers [[RISK-NX-RELEASE]] for versioning. Whether Nx hands the `nx-release-publish` tasks of one group to one batch under `nx release publish` was run later ([[EVD-NX-24-PUBLISH-BATCHES]]).
2540
+ :::
2541
+
2542
+ :::mara evidence EVD-NX-24-BATCHES
2543
+ :mid: 01M7DA96ZTW4EQHXFWV0VTGNEA
2544
+ :title: What Nx 24.0.6 does with the tasks, results, terminal output and cache entries of a batch
2545
+ :status: accepted
2546
+ :supports: ADR-BATCH-EXECUTOR
2547
+ :supports: RISK-BATCH-BEHAVIOUR
2548
+ :supports: RISK-TERMINAL-ENVIRONMENT-MACOS
2549
+ :supports: ADR-CACHED-FAILURES
2550
+
2551
+ Experiments on 14 November 2026 with `nx` 24.0.6, the version this repository installs, Node.js 26.12.0, git 2.56.0 and cargo 1.100.0 on Linux x86-64 with 32 cores, and a reading of that package (paths under `dist/src/`). A throwaway Nx workspace outside the repository held four projects, `a`, `b`, `c` and `d`, where `b` depends on `a` and `d` on `b`, and a local executor `probe:t` with an `implementation`, a `batchImplementation` and `preferBatch: true`, beside `probe:u`, the same without `preferBatch`. Its target `bt` was cached, with the project's `src` folder and `^` over it as inputs, the project's `out` folder as output and `dependsOn: ["^bt"]`. The batch implementation logged what it received, wrote `out/result.txt` for each task and returned for each task `{ success, terminalOutput, startTime, endTime }`, either as one object keyed by task id or from an async generator that yielded `{ task, result }` as each task finished; variables made it fail a task, leave one out, throw, call `process.exit`, report another status or put a warning line at the top of each `terminalOutput`. A local plugin with only the `preTasksExecution` and `postTasksExecution` hooks set a variable and logged the results that it got. Every command ran with `NX_USE_LOCAL=true` and a private `NX_CACHE_DIRECTORY`, without `CI`, `GITHUB_ACTIONS`, `NX_CACHE_FAILURES` and the variables by which Nx detects an AI agent, and with `NX_DAEMON=false`, where a point does not say otherwise. The commands were `nx run-many -t bt`, with the options that each point names, `nx run b:bt`, `nx run c:bt` and `nx affected -t bt --base=main --head=HEAD`.
2552
+
2553
+ - **Batching.** Without `--batch`, `nx run-many -t bt` printed "Running 4 tasks with probe:t" and started one batch process, which received the four tasks, the edges between them and the roots `a:bt` and `c:bt`. `nx run b:bt` gave one batch of `a:bt` and `b:bt`, and `nx run c:bt` a batch of that one task, announced as the command `nx run c:bt`. `--parallel=1` changed nothing. `probe:u` ran each task in a process of its own, and in one batch with `--batch`; `--batch=false` ran the tasks of `bt` one by one. Without `--batch`, the scheduler batches a task only when its executor sets `preferBatch`; it takes each runnable task together with the tasks of the same executor that depend on it, and leaves out a task whose `parallelism` is `false` and a continuous task that another task waits on (`tasks-runner/tasks-schedule.js`, lines 115 to 134, 202 to 258 and 268 to 275).
2554
+ - **What the batch implementation gets.** It gets the batch's task graph, the options of each task keyed by task id, the overrides of the last task, and a context whose task graph is the whole one and which has no `projectName`, `targetName` or `configurationName` (`tasks-runner/batch/run-batch.js`, lines 17 to 38). Its tasks carry no `hash`: Nx removes the hashes, their details, the timings and the terminal output from both graphs before it sends them (`tasks-runner/forked-process-task-runner.js`, lines 60 to 66, and `tasks-runner/prune-task-graph.js`, lines 13 to 19). The batch process had neither `NX_TASK_HASH` nor `NX_TASK_TARGET_PROJECT`, which the process of a task run alone had.
2555
+ - **Results.** Nx takes a task's status from its result's `status`, or else from `success` (`tasks-runner/task-orchestrator.js`, lines 40 to 42), and keeps it as reported. With `b:bt` reported failed, only `b:bt` failed: `d:bt`, which depends on it and was reported successful, succeeded and was stored, and the next run restored `a:bt`, `c:bt` and `d:bt` and ran `b:bt` alone. A task reported as `skipped` made the run exit with status 1 and was listed as not run; it was not stored and was missing from the results that `postTasksExecution` got. What the unknown status `weird` did depends on how the batch returned it. Streamed from a generator, it stopped Nx with "Error: Unknown task status: weird" from `parseTaskStatus` (`task-orchestrator.js`, line 820), exit status 1 and nothing stored, so that the next run restored none of the four tasks. Returned in one object, it left that task unstored, yet the run printed "Successfully ran target bt for 4 projects" and exited with status 0, and the next run restored the three other tasks: the exit status counts only `failure` and `skipped` (`tasks-runner/run-outcome.js`, lines 31 to 39), and without `NX_CACHE_FAILURES=true` Nx stores a batch task only when its status is `success` (`task-orchestrator.js`, line 830 and lines 1880 to 1899). A result without `terminalOutput` made storing it fail: `cache.put` threw "Failed to convert JavaScript value `Undefined` into rust type `String`" (`tasks-runner/cache.js`, line 189, called from `task-orchestrator.js`, line 1850) after the other three tasks had been stored, every task was listed as not run, the exit status was 1, and `postTasksExecution` was not called. With `--skip-nx-cache`, where Nx stores nothing, the same results gave a successful run with exit status 0.
2556
+ - **Tasks left out.** A task that the batch did not report stayed incomplete. Nx stored the three others and started a new batch process for that task alone, and another for as long as it was left out, three times in a row in the experiment; the loop has no limit (`task-orchestrator.js`, lines 708 to 728). `d:bt` had succeeded and been stored before `b:bt`, on which it depends, ran. Read and run again on 20 November 2026 (nxr-k63csj): Nx runs a batch in waves (`applyFromCacheOrRunBatch`, `task-orchestrator.js`, lines 708 to 738), whose comment names tasks "left out by the executor". Each wave hashes the remaining tasks that have no hash yet (`hashBatchTasks`, line 697, and `hasher/hash-task.js`, line 131) and looks up level by level those whose hash is not already a known miss (`fetchCacheHits`, lines 506 to 523, and `cacheMissedHashes`, lines 153 to 158), so that a task left out keeps the hash of the first wave; Nx does not look a known miss up again, and a task left out that it had not looked up before is first looked up in a later wave, as `pc` in the three-wave fixture, which Nx first asked the cache for after it had stored `pb`; a task whose inputs read other tasks' outputs and that runs behind a miss is hashed again only once a batch process has reported it (lines 663 to 667 and 763 to 776). It runs the tasks that it does not restore in one new batch process, stores the results that the process reported and schedules what they unblock (`postRunSteps`, lines 1834 to 1874), and removes the completed tasks; the waves go on while tasks remain and the run has neither bailed nor been stopped. Continuous tasks start in a loop of their own (`executeContinuousTaskLoop`, line 361), which the waves do not hold up. Nx gives the terminal UI the batch's status once, after the last wave, and registers a task against its check for recursive invocations once per `nx` process (`detectTaskInvocationLoop`, lines 445 to 479), so that a task that comes back in a later wave is not taken for a loop. With the plugin compiled from that issue's branch and cargo 1.100.0, in copies of the `workspace-tests` fixture with the binary crates `pa` and `pb`, whose builds differ in environment through `pb`'s `.env`, so that the plugin left `pb`'s whole-workspace group unreported: in the styles `static`, `stream`, `stream-without-prefixes` and `static` with `GITHUB_ACTIONS=true`, and with `dynamic` in a pseudo-terminal through util-linux's `script` without a size, where Nx does not start its terminal UI, the run passed, cargo built the workspace twice, and restoring each crate's build alone gave the executable that its own command had built; with `--skip-nx-cache` it passed and stored nothing. Under the terminal UI, which stayed open for want of `TERM` (below), both tasks showed as done after two builds, and both entries were right. A crate `pc` that depends on `pb`, whose `build` a target default gave `^build`, was left out of the first and second batch processes and ran in a third, and each of the three entries was right. A JS task that depended on both builds ran after the second, and in `nx run-many -t build test` every cargo command of the `test` batch came after both builds. With a compile error in `pa`, `pa:build` failed, `pb`'s group ran in the following process and was stored, and the run exited with status 1; with `--nx-bail`, Nx started no following process, listed `pb:build` under "Tasks not run because their dependencies failed, --nx-bail=true, or their batch ended before reaching them", stored nothing for it and exited with status 1. In the static styles, Nx announced a following process of one task by that task's command, `> nx run pb:build`, before the task's own header. After each run, `pa`'s executable in the artifact directory was the one that `pb`'s build of the whole workspace had linked last, with the flag, while its entry held its own. `script` gives its terminal no size, with which Nx does not start the terminal UI that `--tui` asks for ("Nx Terminal UI was not enabled as it is not supported in this environment", `tasks-runner/is-tui-enabled.js`, lines 27 to 38), and with `NX_TUI_SKIP_CAPABILITY_CHECK=true` its pseudo-terminal panicked before any task ran; given 160 columns and 48 rows with `stty`, the terminal UI ran, and `dynamic` became it, and showed every task done, but did not exit with `--tui-auto-exit=true`, with a task left out or without one, until `timeout` ended it. Run again on 21 November 2026 (nxr-h411yj): those runs had no `TERM`, as the agent's shell that started them had none. In a minimal workspace of two `nx:run-commands` tasks and a terminal of 120 by 35, `nx run-many --tui --tui-auto-exit=true` showed both tasks done and stayed open until `timeout` ended it, after 25 seconds, with `TERM` unset and with `TERM=dumb`; with `TERM=xterm` or `xterm-256color` it closed by itself and exited with status 0 about 2.4 seconds after it started, with `--tui-auto-exit=true`, with a bare `--tui-auto-exit` and with `--output-style=dynamic`, and without `--tui-auto-exit` 3 seconds later, the default countdown of `tui.autoExit` (`schemas/nx-schema.json`). Where in Nx's native terminal UI `TERM` decides this was not read. With `TERM=xterm-256color` and that size, the plugin compiled from `main` ran the builds of `pa` and `pb`, two groups of one batch, under the terminal UI, which closed by itself; cargo built the workspace twice and each restored crate printed what its own command built. A batch that leaves a task out, which the plugin no longer makes (nxr-yfh7zh), was not run again. A bare `--tui-auto-exit` sets a countdown of 0 seconds, not `true` (`command-line/yargs-utils/shared-options.js`, lines 411 to 423). A review of nxr-k63csj on 20 November 2026 ran, with the same Nx and cargo, what these runs left out. A continuous `watch` target that depends on `pa:build`, run through a consumer beside both builds with `--parallel=3`, started between the wave of `pa` and that of `pb`, while discrete dependents waited through both waves. A cached `pack:pack` that depends only on `pa:build`, with the inputs `default` and `^default`, and writes `dist/pa.txt` from the output of `rust/target/debug/pa`, ran in `nx run-many -t build pack -p pa pb pack --parallel=3` after the wave of `pb` had linked `pa` again, and stored `flag`; after `dist` was deleted, `nx run pack:pack` restored a `dist/pa.txt` with `flag` beside a restored `pa` that prints `plain` (nxr-yfh7zh). Each build's own entry held its own files byte for byte, also through a remote cache that stored with a delay. With `{ "dependentTasksOutputFiles": "**/pb" }` added to the inputs of `build` in the fixture of `pa`, `pb` and `pc`, a repeated command restored `pa` and `pb` and ran cargo again for `pc`, whose first-wave key the next command computed differently: a miss. A cache trace of the cold run shows Nx asking for and storing `pc` under the hash it computed before `pb` ran; whether that key can match a result built from another output of `pb` was not run (nxr-f04xen).
2557
+ - **A throw or an exit.** When the batch implementation threw while it ran `d:bt`, Nx printed the error's message; when it called `process.exit(7)` there, Nx printed nothing about it. Either way it marked all four tasks failed, `a:bt` and `b:bt` too, which the generator had already reported successful and whose output Nx had already printed, and it stored nothing (`run-batch.js`, lines 62 to 69, and `task-orchestrator.js`, lines 845 to 858), unless `NX_CACHE_FAILURES` was `true` (next point).
2558
+ - **`NX_CACHE_FAILURES`.** With `NX_CACHE_FAILURES=true`, Nx stores failed tasks too (`task-orchestrator.js`, lines 2097 to 2099). A batch that threw stored a failure for each of its four tasks, and the next run printed the four stored failures, with the message `"probe:t" exited unexpectedly with code: 1`, and exited with status 1 without starting a batch. A task that the batch reported failed was stored and replayed in the same way, beside the three that succeeded. Outside batches, the plugin as it is on `main`, compiled from `nx-rust/src` at 3445ae7, which runs one cargo command per task, does the same under this setting. A failing integration test of `a` was stored, and the next run printed the same panic line, thread id included, while `target/`, deleted in between, stayed absent. A cached `build` that the executor failed before cargo ran, because a `CARGO_BUILD_TARGET` in `a/.env` picked a triple that its outputs did not name, left a cache entry, which it did not without the variable, and the next run printed a line that had been added to the stored output.
2559
+ - **Restoring.** With every task stored and the source of `b` changed, Nx restored `a:bt` and `c:bt` and printed their stored output before it started the batch, which received only `b:bt` and `d:bt`, without the edge from `b:bt` to `a:bt`. Nx hashes each task of a batch with that task's own environment, and looks each level of the batch's graph up in the cache before it runs what is left (`task-orchestrator.js`, lines 630 to 707). A run with `--batch=false` restored all four tasks that a batch had stored, as [[EVD-NX-24-INPUT-SEMANTICS]] found.
2560
+ - **Storing.** Nx stores the results of a batch when the batch process has returned them all, not as each task finishes (`task-orchestrator.js`, lines 739 to 780 and 1834 to 1874). With a generator that reported the four tasks 700 ms apart, the cache folder held no entry while the batch ran, and the four entries were written within 3 ms of its end. The stored terminal output of a task was exactly its result's `terminalOutput`; what the batch process printed itself was in no entry. The stored outputs are the files at the task's declared outputs when the batch ends, whoever wrote them: in a batch where `d:bt` wrote `a`'s `out/result.txt` after `a:bt` had been reported, the entry of `a:bt` held what `d:bt` had written, and a later run restored that into `a`'s folder.
2561
+ - **Cargo in one batch.** In a Cargo workspace whose member `a` has a binary and an integration test, depends on a path crate `f` and enables `f`'s feature `extra` as a dev-dependency, `cargo test -p a` replaced the binary `target/debug/a` that `cargo build -p a` had written with one built with `extra`, and `cargo build -p a` wrote the first one back. An executor whose batch implementation ran a `build` group and then a `test` group, `build` declaring `target/debug/a` as its output, made Nx store the binary built with `extra` under the key of `a:build`, and `nx run a:build` restored it after the binary had been deleted. With `--batch=false --parallel=1`, the same two tasks stored and restored the binary built without `extra`. A restored result is no protection either, and that does not depend on batching. With a fresh cache, `nx run a:build`, the deletion of `target/debug/a` and `nx run a:test`, `test` depending on `build`, restored `a:build`, ran only `a:test` in the batch and left on disk the binary built with `extra`; the entry of `a:build` stayed right, for deleting the binary and restoring it again gave the binary built without `extra`. The same sequence with `--batch=false` left the same binary on disk, and so did the plugin as it is on `main`, whose `test` does not depend on `build`, for `nx run a:build`, the deletion and `nx run-many -t build test -p a`, after which its entry for `a:build` also restored the binary built without `extra`. Plain `cargo build -p a` followed by `cargo test -p a` leaves that binary as well: after a command that runs both, the artifact directory held what cargo wrote last, with a batch or without one, in the plugin of that day; since nxr-5hzxra a `test` batch puts back what `build` stored ([[DES-BATCH]], "Files that a test batch puts back").
2562
+ - **Terminal output.** The batch process's standard output and error are pipes, and Nx writes what arrives on them to the terminal at once in every style that prints task output, apart from GitHub Actions' grouping and the terminal UI (`tasks-runner/forked-process-task-runner.js`, line 43, and `tasks-runner/running-tasks/batch-process.js`, lines 113 to 131). Nx prints a task's own `terminalOutput` while the batch runs only for a result that an async generator streams, as it arrives (`task-orchestrator.js`, lines 795 to 821, and `run-batch.js`, lines 42 to 58). With one object of results, `--output-style=static` showed the batch's own lines and the output of no task, not even of the failed `b:bt`. With a generator, in a run that restored `a:bt` and `c:bt` and ran `b:bt` and `d:bt`, each with a warning line at the top of its `terminalOutput`:
2563
+ - `static`, `stream` and `stream-without-prefixes` printed the stored output of `a:bt` and `c:bt` under `[local cache]`, warning line included, then the batch's own lines and, as each task was reported, its block with the warning line first; `stream` put no project prefix on the batch's lines.
2564
+ - `static-failures-only`, the style of a run that names none and has no terminal, showed one line for each successful task, restored or run, the full block of a failed one, and the batch's own lines in full.
2565
+ - `summary` printed counts, for a failed task the path of its stored output, which held its warning line and its output, and the path of the batch's own log in the cache folder's `batchOutputs`.
2566
+ - Under a pseudo-terminal, `dynamic-legacy` showed the batch's own lines, one line for each successful task and the block of the failed one. `dynamic` and `tui` both open the terminal UI (`tasks-runner/is-tui-enabled.js`, lines 47 to 49), which showed a row for each task, with its status and whether it came from the cache, and a row for the batch.
2567
+ - With `CI=true` and `GITHUB_ACTIONS=true`, as GitHub Actions sets them, the batch's own lines went into a fold labelled "batch probe:t 1", because a task had failed, and the tasks then printed as in `static-failures-only`, the failed one in a fold of its own, for one object of results and for a generator alike (`task-orchestrator.js`, lines 839 to 841 and 990 to 1014).
2568
+
2569
+ A line that the batch process prints itself therefore belongs to no task: it is not stored and not replayed. A line at the top of a task's `terminalOutput` is printed with that task, stored with it and replayed with it from the cache.
2570
+
2571
+ Run again on 15 November 2026 for nxr-8f9dz2, with the plugin compiled from the branch of nxr-s12cpg and copies of it that set `preferBatch: true` and that also write cargo's output to the batch process's standard error as it arrives, in a copy of the `batch-groups` fixture whose build script and integration tests take several seconds, timed line by line, in a pseudo-terminal through util-linux's `script` and in a tmux pane of 120 by 36 for the terminal UI:
2572
+ - Nothing of cargo reaches the terminal while a batch runs, in any style, where the batch writes cargo's output only to the file that feeds each task's result; each task's block appears when its group has run. Without a batch, cargo's lines appear as they come in `stream`, `stream-without-prefixes` and the terminal UI, in the last with colours and cargo's progress bar where Nx gives the task a pseudo-terminal, and in the static styles at the end of each task.
2573
+ - Lines that the batch process writes itself appear as they come in `static`, `stream` and `stream-without-prefixes`, with no project prefix, and are then printed again in each task's block, so that every line shows twice; in `static-failures-only` a failed task's lines show twice. `dynamic-legacy` redraws its status block over them, so that most of them are lost. The terminal UI shows them as they come in the batch's pane, once, while each task's pane gets its block when the task is reported; it keeps them in `batchOutputs` in the cache folder where a task failed. `summary` only keeps them there. Under GitHub Actions' grouping (`CI=true` and `GITHUB_ACTIONS=true`), Nx holds back the batch's own lines and the results that the generator streams until the whole batch has ended (`task-orchestrator.js`, line 812), and shows the batch's lines only in a fold where a task failed.
2574
+ - The batch process can tell the terminal UI apart, where Nx sets `NX_TUI=true` in its environment and `false` otherwise, and GitHub's grouping by `GITHUB_ACTIONS`; `NX_STREAM_OUTPUT=true` comes with `stream`, `stream-without-prefixes`, `--batch` and the terminal UI, and `static`, `static-failures-only`, `dynamic-legacy` and `summary` look the same to it.
2575
+ - Cargo writes to a pipe or a file in a batch, so it shows no colours and no progress bar there; cargo also hides its progress bar wherever `CI` is set, `CI=false` included.
2576
+
2577
+ - **Other tasks.** The coordinator awaits a batch before it dispatches anything else (`task-orchestrator.js`, lines 329 to 347). The published reproduction, at commit `90cdbe8`, with its implicit dependencies written `batch-a` in place of `:batch-a`, which Nx 24.0.6 rejects as pointing to no project, ran `nx run-many -t build --skip-nx-cache --parallel=2 --output-style=static` twice. Its batch of `batch-a` and `batch-b` ran for 10 s, and `independent`, which depends on nothing, started 21 ms and 22 ms after the batch ended, within 5 ms of `dependent`, which depends on `batch-a` only and still waited for the whole batch, though the generator had reported `batch-a` 5 s before its end. Nx 24.0.6 has no `batchParallelismCost`, which the reproduction's executor declares. In the workspace above, with each `bt` task depending on an uncached task `lock:lockfile` that took 1 s, beside four tasks `js` of `nx:run-commands` that took 3 s each, `nx run-many -t bt js --parallel=3` started the lockfile task and two `js` tasks together, the batch 65 ms after the lockfile task ended, and the two other `js` tasks 20 ms and 22 ms after the batch ended, 8 s later. The two `js` tasks that had started before the batch ran on beside it, and for the last 6 s of the batch no other task ran.
2578
+ - **Environment.** The batch process got the environment of the `nx` command with the repository's root `.env` files, which Nx builds once per command (`task-orchestrator.js`, line 144, and `tasks-runner/task-env.js`, lines 36 to 51), as [[EVD-NX-24-INPUT-SEMANTICS]] found: with `PROBE_VAR` set in `libs/d/.env`, the process of `d:bt` run alone had it, and the batch process had not. A variable that `preTasksExecution` assigned reached the batch process, with and without the daemon, because Nx calls that hook before it creates the orchestrator (`tasks-runner/run-command.js`, lines 355 to 385, and `project-graph/plugins/tasks-execution-hooks.js`, lines 17 to 54). With `--skip-nx-cache`, the batch received every task, those stored before too, its process had `NX_SKIP_NX_CACHE=true`, and Nx stored nothing. The batch process's standard output is a pipe in every style, so cargo started from it sees no terminal.
2579
+ - **Task environment.** Read in that package on 14 November 2026 (nxr-s12cpg), and run with the plugin's batch executor. For a task run on its own, Nx builds the environment in this order. First `getTaskSpecificEnv` (`tasks-runner/task-env.js`): a copy of the `nx` process's environment without each variable whose value the repository's root `.env`, `.local.env` or `.env.local` gives, with the task's dotenv files loaded, those of the project's folder first and then those of the root, each for the target and configuration and then the plain ones. Then `getEnvVariablesForTask`, as `task-orchestrator.js` (lines 1169 to 1171) calls it with the task's hash, its output path in the cache folder and whether its output streams, or, where Nx pipes the task's output, without the last two and with `getForceColorForChild()`: it lays over that `FORCE_COLOR`, which is undefined where Nx writes the output to a file, so that Node leaves it out of the child's environment, `NX_WORKSPACE_ROOT`, `NX_SKIP_NX_CACHE`, `NX_INVOCATION_ANCESTOR_PIDS` with the `nx` process's id appended, with an output path `NX_TERMINAL_OUTPUT_PATH`, `NX_TERMINAL_CAPTURE_STDERR` and `NX_STREAM_OUTPUT`, then `NX_TASK_TARGET_PROJECT`, `NX_TASK_TARGET_TARGET`, `NX_TASK_TARGET_CONFIGURATION`, `NX_TASK_HASH`, `LERNA_PACKAGE_NAME`, `NX_TERMINAL_CAPTURE_STDERR=true` for a target named `test`, and `NX_TUI=false`; it deletes `NX_TERMINAL_OUTPUT_PATH`, `NX_STREAM_OUTPUT` and `NX_PREFIX_OUTPUT` where there is no output path, and always `NX_SET_CLI`, `NX_ORIGINAL_FORCE_COLOR`, `NX_READY_SIGNAL_SOCKET`, `NX_READY_SIGNAL_TASK` and `NX_READY_URL`. The orchestrator then adds `NX_READY_URL` where exactly one continuous task that the task depends on has reported ready at a URL (`getReadyUrlEnv`), the fork adds `NX_FORKED_TASK_EXECUTOR=true` (`forked-process-task-runner.js`), and the task's process sets `NX_CLI_SET=true` (`bin/run-executor.js`). A batch process gets the `nx` process's environment with `FORCE_COLOR` from `getForceColorForChild()`, `NX_WORKSPACE_ROOT`, `NX_SKIP_NX_CACHE` and `NX_INVOCATION_ANCESTOR_PIDS` as a task gets them, without `NX_ORIGINAL_FORCE_COLOR` and the ready-signal variables (`getEnvVariablesForBatchProcess`), with `NX_FORKED_TASK_EXECUTOR=true` and, set by `batch/run-batch.js`, `NX_CLI_SET=true`. Read on 15 November 2026 after a second review, the places that change the environment on the way from the `nx` command to a task, beyond those: the `nx` process itself sets `NX_CLI_SET=true` (`bin/init-local.js`, line 19); turns `FORCE_COLOR=0` into `NX_ORIGINAL_FORCE_COLOR=0` and `NO_COLOR=1` (`bin/nx.js`, lines 7 to 10); sets `NX_DAEMON=false` only for commands that run no task, such as `nx new`, `nx init` and `nx graph` outside a workspace (lines 77 and 123); sets `NX_VERBOSE_LOGGING` to `true` or `false` from `--verbose` in every command (`command-line/yargs-utils/shared-options.js`, line 172, and `command-line/run-many/run-many.js`, line 24), `NX_TUI_AUTO_EXIT` from `--tui-auto-exit` (line 52) and `NX_TUI` from the output style and the terminal UI (line 335, and `tasks-runner/run-command.js`, line 89); sets `NX_STREAM_OUTPUT` and `NX_PREFIX_OUTPUT` for the style `stream`, for `stream-without-prefixes`, for `--batch` and for the terminal UI, and `NX_LOAD_DOT_ENV_FILES=true` (`run-command.js`, lines 669 to 691); sets `NX_ANALYTICS_SESSION_ID` once per command where its analytics are on (`analytics/analytics.js`, line 108); and takes over the variables that a `preTasksExecution` hook sets, with the daemon as without it (`project-graph/plugins/tasks-execution-hooks.js`, line 51). The daemon changes only its own environment (`daemon/client/daemon-environment.js`). Each way of forking a task adds `NX_FORKED_TASK_EXECUTOR=true` after the task's environment, and so does the batch's fork (`forked-process-task-runner.js`, lines 33 to 46, 130 to 139, 169 to 179 and 212 to 222). Nx runs a single task in its native pseudo-terminal where the terminal UI is on, or where the output streams without prefixes, as with `dynamic-legacy` and `stream-without-prefixes` in a terminal (`forkProcess`, lines 92 to 128); the pseudo-terminal starts `tasks-runner/fork.js` with `NX_PSEUDO_IPC_PATH`, `NX_PSEUDO_IPC_FORK_ID` and `NX_PSEUDO_TERMINAL_EXEC_ARGV`, Nx's own `execArgv` joined by `|`, and `fork.js` deletes the first two, and the third only where it is not empty (lines 7 to 16), so that a task in the pseudo-terminal of an `nx` process without `execArgv` gets `NX_PSEUDO_TERMINAL_EXEC_ARGV` empty. In a terminal, Nx 24.0.6 also asks whether to share usage data and waits, unless `nx.json` sets `analytics` to a boolean or Nx detects CI (`utils/analytics-prompt.js`, lines 21 to 38). An integration test and a build script that wrote their whole environment, in the plugin's batch-groups fixture with dotenv files in the crate's folder and at the root, ran through the plugin with these layers rebuilt in the batch: alone and with `--batch`, each in the styles `static`, `stream` and `static` with `--verbose`, and, in a pseudo-terminal through util-linux's `script` with `analytics: false`, `static`, `stream-without-prefixes`, `dynamic-legacy`, `dynamic` with `--tui-auto-exit` and the terminal UI with `--tui --tui-auto-exit`, each without the daemon and with it, chosen in `nx.json`. With only `NX_TASK_HASH`, the output variables and `FORCE_COLOR` left out, all 32 runs gave the same environment apart from `NX_INVOCATION_ANCESTOR_PIDS`, `NX_RUST_COMMAND_ID` and `NX_RUST_NX_COMMAND`, which differ between any two `nx` commands, and three variables: `NX_PSEUDO_TERMINAL_EXEC_ARGV`, empty, in the four single tasks in Nx's pseudo-terminal, `NX_TUI_AUTO_EXIT=0` where the command had `--tui-auto-exit`, alone and batched, and `NX_VERBOSE_LOGGING=true` where it had `--verbose`, against `false`. No run differed in `TERM`, `COLUMNS`, `LINES` or `CI`, by the daemon, or in the dotenv values. With those three, the pseudo-terminal's other two and `NX_ANALYTICS_SESSION_ID` left out as well, the same ways of running give the same environment apart from the three per-command variables. The runs of `dynamic` and of the terminal UI had a terminal without a size, in which Nx 24.0.6 does not start its terminal UI ("Tasks left out"); run again on 21 November 2026 (nxr-h411yj) with those two in a terminal of 120 by 35, where Nx started its terminal UI, every way with `TERM=xterm-256color`, and the plugin leaving out only `NX_TASK_HASH`, the output variables, `FORCE_COLOR` and the four variables that the pseudo-terminal gives back, the 22 runs of the plugin's test, alone and with `--batch`, without the daemon and, for `static`, `stream-without-prefixes` and the terminal UI, with it, differed in the same three variables and nothing else: `NX_PSEUDO_TERMINAL_EXEC_ARGV`, empty, in the six single tasks in Nx's pseudo-terminal, `NX_TUI_AUTO_EXIT=0` where the command had `--tui-auto-exit`, and `NX_VERBOSE_LOGGING=true` with `--verbose`. Under the terminal UI no other variable reached the test or the build script, and no run differed in `COLUMNS` or `LINES`. With only `getTaskSpecificEnv`, as the batch first rebuilt it, the batched test lacked `NX_TASK_TARGET_PROJECT` and the other per-task variables. Read and run on 15 November 2026 after a third review: Nx's native pseudo-terminal builds a task's process with portable_pty's `CommandBuilder` from the `nx` process's own environment and sets each variable of the environment that Nx built for the task over it (`native/pseudo_terminal`). A variable that `getEnvVariablesForTask` deletes or leaves without a value therefore comes back with the `nx` process's value for a task in a terminal: with `NX_SET_CLI` set, `FORCE_COLOR=0` and `NX_TASK_TARGET_CONFIGURATION=outer` in the command's environment, a task alone in `stream-without-prefixes` or the terminal UI got `NX_SET_CLI`, `NX_ORIGINAL_FORCE_COLOR=0` and `NX_TASK_TARGET_CONFIGURATION=outer`, which the same task alone in `static` and in a batch lacked; `NX_SKIP_NX_CACHE`, which the layer leaves without a value where the run does not skip the cache, comes back the same way. With the root `.env` holding `NX_FORKED_TASK_EXECUTOR=true` and `NX_CLI_SET=true` and the task's `.env.test` holding both as `false`, the task alone got `true` for both, which the fork and `bin/run-executor.js` set after the dotenv layer, while the batch, whose process has both from its start, got `false`: `getTaskSpecificEnv` removed the root values, which equal the process's, and the task's file gave its own. Whether Nx loads a task's files at all comes from the `nx` process's environment: `nx run`, `run-many`, `affected` and `release publish` load them unless `NX_LOAD_DOT_ENV_FILES` is `false` (`command-line/run/run-one.js`, line 22, and the others), after the `nx` process has loaded the root `.local.env`, `.env.local` and `.env`, the first that defines a variable giving its value, without changing a variable that the command sets (`utils/dotenv.js`, `loadRootEnvFiles`, called from `bin/workspace-env.js` when the process starts); the run then sets the variable to `true` (`run-command.js`, line 690), and `getTaskSpecificEnv` reads it when it builds the task's layer. Without loading, `getTaskSpecificEnv` still removes the root files' values from the task (lines 68 to 72) and loads none back. `nxArgs.skipNxCache` is also on where `NX_SKIP_NX_CACHE` or `NX_DISABLE_NX_CACHE` is `true` (`utils/command-line-utils.js`, lines 117 to 121).
2580
+ - **Dotenv expansion.** Read on 15 November 2026 (nxr-s12cpg) in dotenv 16.4.7 and dotenv-expand 12.0.3, the versions that Nx 24.0.6 pins exactly, and checked against them in the plugin's tests. `getTaskSpecificEnv` copies the environment of the process it runs in, deletes each variable whose value equals the one that the root `.env`, `.local.env` or `.env.local` gives, parsed on its own with only its own variables in scope, and loads the task's files with `loadAndExpandDotEnvFile`. dotenv's `config` parses the files in order and keeps for each variable the first file's value, sets in the environment only variables that it lacks, also where the environment's value is empty, and reads a `.vault` file instead where `DOTENV_KEY` is set and a vault lies beside the last file that exists, or beside a root file for the deletion (`lib/main.js`, `config`, `_vaultPath` and `populate`). dotenv-expand then takes, for each variable of the files, the environment's value where that is not empty and differs from the file's, and else expands the file's value (`lib/main.js`, `expand`): it finds the leftmost `${…}` or `$NAME` not preceded by a backslash, takes the name before the first of `:+`, `+`, `:-` and `-`, splitting and joining with `null` where there is none, which JavaScript turns into the separator `null`, puts in the environment's value, which wins over earlier variables of the files, or the default, with `String.prototype.replace`, and searches again from the start (`expandValue`). It therefore expands what it put in: a value of the command's environment such as `${FORCE_COLOR}` that a file refers to, or the raw value of another file's variable, brings references of its own, and a reference can be assembled from a substituted value and the file's text, as `${FORCE_${PART}}` with `PART=COLOR` or `$${NAME}` with `NAME=FORCE_COLOR` look up `FORCE_COLOR`. A rule that looks only for the names written in a task's files misses these. Within one call, each name has one value in dotenv-expand's environment, since `expand` writes its results only after it has expanded every variable. dotenv-expand has no limit, and does not end in two ways: where the substituted value refers to the variable that it came from with text around the reference, as `A=x${A}` read through `B=${A}z`, no result ever equals one seen before and the value grows with every step; where values refer to each other without text, as `x${A}` with `A=${B}` and `B=${A}`, it comes back to a result that it had and repeats the same steps without growing. Only a result that holds a reference enters its set of earlier results, so only a value with `$` is ever blocked. On 15 November 2026 (nxr-s12cpg, fourth review), cases of the seeded test of random files that the check stopped were replayed through Nx's `loadAndExpandDotEnvFile` in worker threads, with 1.5 seconds and 256 MB each. That a name is put in again inside the text of its own earlier insertion is necessary for an expansion that grows without end, but not sufficient: of 316 cases that a bound on the first such repetition stopped, 250 ran out of memory, 50 out of time and 16 ended with short values, through a value equal to an earlier result or the stop on a result equal to the variable's value. Of 1,012 cases that the former `dotenv-expand` 12.0.3 follower's bounds stopped (a cycle, more than 64 nestings, 131,072 characters or 1,000,000 steps; replaced by the static check of [[DES-BATCH]], "Dotenv files", see [[EVD-DOTENV-STATIC-CHECK]]), sampled from the 2,500 default seeds and from 10,000 others, none ended: 837 ran out of memory and 175 out of time. In 12,500 generated cases, the expansions that ended nested a name at most five times. One regular expression for each earlier result that holds a placeholder exhausted the heap on 373 references to a command variable whose value refers to two variables of the files. With `DOTENV_KEY` set, dotenv reads the root files' vaults where Nx removes their values from a task, `.env.vault` beside a root `.env` that does not exist included, whether or not Nx loads the task's files, and writes to the console that it reads a vault, or a warning where it finds none. A batch process lacks `NX_ORIGINAL_FORCE_COLOR`: a root `.env.local` with `NX_ORIGINAL_FORCE_COLOR=${CMD}z`, with `FORCE_COLOR=0` and `CMD=x${CMD}` in the command, made dotenv-expand run out of heap in the batch, while the `nx` process, which has `NX_ORIGINAL_FORCE_COLOR=0` from `FORCE_COLOR=0`, takes its own value and does not expand the file's. That a file defines a variable that can differ between the processes changes nothing that cargo sees only where each such variable is left out of cargo's environment, set by Nx after the files for every task, or set after them in a batch as Nx sets it after them for a task run on its own: the first reading of 15 November 2026 overlooked `NX_FORKED_TASK_EXECUTOR` and `NX_CLI_SET`, which a batch process has before the batch lays the task's files over it, and which a third review found ("Task environment").
2581
+ - **Hooks.** Each command called `preTasksExecution` once before its first task and `postTasksExecution` once after its last, with the status and code of every task, batched or not, apart from a task that a batch reported as `skipped`.
2582
+ - **Daemon and affected.** With the daemon started and `NX_DAEMON=true`, the batches, the tasks they received and the restoring were the same; a restored task whose outputs were already on disk was reported as "existing outputs match the cache, left as is". After a commit that changed `b`, `nx affected -t bt --base=main --head=HEAD` ran `a:bt`, `b:bt` and `d:bt` in one batch.
2583
+ - **Dependents of a failed task.** Read, not run, on 14 November 2026 after an independent review: when a task completes as failed, skipped or stopped, Nx marks every task that depends on it, and is not already running, as skipped (`complete`, `task-orchestrator.js`, lines 2039 to 2058), and the results it stores leave out every skipped task before `shouldCacheTaskResult` decides on `NX_CACHE_FAILURES` (`resultsToCache`, lines 1880 to 1898, and lines 2097 to 2100). A skipped task is therefore never stored, also with `NX_CACHE_FAILURES=true`, and its key gets no entry.
2584
+ - **Continuous tasks.** Read, not run: a continuous task that another task waits on, or that has a readiness check, never joins a batch, and continuous tasks are started by a loop of their own, which a running batch does not hold up (`tasks-schedule.js`, lines 210 to 218, and `task-orchestrator.js`, lines 361 and 405). Run on 15 November 2026 for nxr-8f9dz2 with the plugin compiled from the branch of nxr-s12cpg, once as it is and once with `preferBatch: true`, in a copy of the `batch-groups` fixture with a project `svc` whose targets `serve` and `serve-ready` are continuous `nx:run-commands` that start a Node server, `serve-ready` with `"readyWhen": { "signal": true }` and a call of `emitReadySignal` once the server listens, and a test of `indep` that writes `NX_READY_URL` to a file:
2585
+ - A task that depends on a continuous task joins a batch once that task has started, or has reported ready where the edge waits for it, also without `--batch` where its executor sets `preferBatch` (`tasks-schedule.js`, lines 207 to 218 and 268 to 287): Nx printed `Waiting for "svc:serve-ready" to be ready...` and then started the batch with `indep:test`.
2586
+ - Nx gives a task run on its own `NX_READY_URL` only through an edge with `waitFor: "ready"` to a continuous task whose `readyWhen` reports ready by `signal`, the only check that reports a URL, and only where exactly one such task reported one (`getReadyUrlEnv`, `task-orchestrator.js`, lines 1638 to 1643, and `mayReportReadyUrl`, `readiness/ready-when.js`): the test saw `http://127.0.0.1:<port>/` with the port that the server chose, and `<unset>` through an edge to the plain `serve`, which has no check. Checks by `url`, `port`, `command` or `logMatches` report no URL. The batch process gets the environment that Nx builds once per command and never a task's URL (`task-orchestrator.js`, line 144, and `task-env.js`, lines 36 to 50), and in the batch the test saw `<unset>` where the task alone had the URL.
2587
+ - A plugin cannot keep such a task out of a batch within Nx 24: `preferBatch` belongs to the whole executor, Nx rejects `parallelism: false` on a task with a continuous dependency ("The following tasks do not support parallelism but depend on continuous tasks"), and a task that the batch does not report runs again in another batch process. `--batch=false` turns batching off for one command, and `NX_BATCH_MODE=false` in the root `.env` for every command of the repository, the batches of other plugins included: with it, both tests ran alone and the test saw its URL.
2588
+
2589
+ These results confirm on Nx 24.0.6 what [[ADR-BATCH-EXECUTOR]] relies on: each task of a batch has its own key, its own restore, its own stored result and its own terminal output, and a restored task takes no part in the batch. They confirm the waiting that [[RISK-BATCH-BEHAVIOUR]] records. They contradict an assumption of [[DES-BATCH]], that the groups of a batch can run one after another while Nx stores each task's result as it would for the task run alone: Nx stores the declared outputs of every task only when the whole batch has ended, so a later group that writes them changes what Nx stores under an earlier task's key, as `cargo test` does with the executables that `build` declares. That a later `cargo test` replaces on disk the executable that a restored `build` put back is not a matter of batching: it happens without a batch too. The experiments of 14 November 2026 used stand-in executors and a small Cargo workspace on one machine, and the plugin compiled from `main` only for the checks outside batches; the later runs dated in the points above ran the plugin's own batch executor, compiled from the branch or `main` that each names, such as the batches of the builds of `pa` and `pb` and the environment comparison under the terminal UI on 21 November 2026 (nxr-h411yj); other Nx versions and macOS were not tried, and the terminal UI was read from a captured screen only.
2590
+ :::
2591
+
2592
+ :::mara evidence EVD-HAKARI-UNIFICATION
2593
+ :mid: 01M7D9EQW8FQW9BAEZSHQ37116
2594
+ :title: What cargo-hakari unifies between the crates of a workspace, and what still depends on the crates built together
2595
+ :status: accepted
2596
+ :supports: RISK-HAKARI-GAPS
2597
+
2598
+ Experiments on 14 November 2026 on Linux x86-64 with cargo 1.100.0, the central case repeated with cargo 1.91.0, and cargo-hakari 0.9.39 (library `hakari` 0.18.0), installed for the experiment into a folder of its own, in throwaway folders outside this repository. The workspace, with resolver 2, had the members `a`, `b`, `c` and `d`. Three path crates outside it stood in for third-party crates: `x`, `y`, and `z`, which depends on the member `c` with its feature `fz`. `c` has the default feature `cdef` and the features `fa`, `fb`, which enables `x/fb`, and `fz`. `a` depends on `c` with `default-features = false` and `fa`, on `x` with `fa`, on `smallvec = "=1.15.1"` from crates.io with `write`, and on `y` with `h1` as a build dependency. `b` depends on `c` with `fb`, on `smallvec` with `union`, on `y` with `h2` as a build dependency, on `x` with `fdev` as a dev-dependency and on `x` with `funix` under `[target.'cfg(unix)'.dependencies]`. `d` depends on `z`. `cargo hakari init`, `generate` and `manage-deps` set up the hack crate with the configuration that `init` writes, whose `platforms` list is empty. Each selection was built with `cargo build -v` in an empty target directory, whose rustc lines show the features of each crate, and the binaries `a`, `b` and `d` printed the features that their crates were compiled with.
2599
+
2600
+ | Features of | Without the hack crate | With the hack crate |
2601
+ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2602
+ | `smallvec`, from crates.io | `write` with `-p a`, `union` with `-p b`, both with `-p a -p b` and `--workspace` | `union` and `write` in every selection |
2603
+ | `y`, a build dependency | `h1` with `-p a`, `h2` with `-p b`, both together | `h1` and `h2` in every selection, through the hack crate's `[build-dependencies]` |
2604
+ | `x`, also a dev-dependency of `b` | `fa` with `-p a`; `fb` and `funix` with `-p b`; no feature with `-p c`; `fdev` only in `cargo test -p b` | `fa`, `fb` and `fdev` in every selection, also in `cargo build`: the hack crate lists the dev-dependency's feature as a normal dependency |
2605
+ | `x/funix`, only under `cfg(unix)` | only with `b` selected | only with `b` selected while `platforms` is empty; in every selection once it lists `x86_64-unknown-linux-gnu`, through `[target.x86_64-unknown-linux-gnu.dependencies]` |
2606
+ | the member `c` | `fa` with `-p a`; `cdef` and `fb` with `-p b`; `cdef`, `fa` and `fb` with both; `cdef` with `-p c`; `cdef` and `fa` with `-p a -p c`; `fz` added with `d` | the same: the hack crate names no member |
2607
+ | `z`, asked for `zf2` by `a` and `zf1` by `d` | not run | `zf2` with `-p a`, `zf1` and `zf2` with `-p a -p d`: the hack crate leaves out a crate that depends on a member through a normal dependency |
2608
+
2609
+ - **Members.** With the hack crate current and the host listed in `platforms`, `target/debug/a` printed `c[fa]` after `cargo build -p a`, `c[cdef,fa,fb]` after `cargo build -p a -p b`, and `c[fa]` again after another `cargo build -p a`, which compiled nothing: cargo keeps both builds of `c` and of `a` side by side under different metadata hashes and links the one of the selection. cargo 1.91.0 gave the same features and the same sequence. `hakari` never puts a workspace member into the hack crate (`StructuralExcludes::never_unified`, `hakari/src/hakari.rs`), and never a third-party crate that depends on the hack crate or on a member that it manages through normal or build dependencies, directly or through other crates, a "structural exclude", whose own dependencies it still unifies. It follows target-specific dependencies for this whatever `platforms` lists, and not dev-only ones, through which Cargo allows cycles (`Hakari::structural_excludes`, `hakari/src/hakari.rs`).
2610
+ - **A dev-dependency on a member.** The review of this spike found that a crate outside the workspace with only a dev-dependency on a member, asked for one feature by each of two members, went into the hack crate with both features, gave the same features in both selections and passed `verify`. A rerun on 14 November 2026 with cargo 1.100.0 and cargo-hakari 0.9.39, in a workspace of its own with the members `a`, `b` and `c`, confirmed it: `w`, with a dev-dependency on `c`, and `z`, with a normal dependency on `c`, were asked for `wf1` and `zf1` by `a` and for `wf2` and `zf2` by `b`. `generate` gave the hack crate `w` with `wf1` and `wf2` and no `z`; `w` had both features with `-p a` and with `-p a -p b`, while `z` had `zf1` with `-p a` and both with `-p a -p b`; `verify` and `generate --diff` passed.
2611
+ - **What recompiles.** In one target directory, the selections `-p a`, `-p a -p b`, `-p a`, `-p b`, `-p c` and `-p a` compiled `y x smallvec c a`, `y x smallvec c a b`, nothing, `y x smallvec c b`, `x c` and nothing without the hack crate, and `y smallvec x workspace-hack a c`, `b c a`, nothing, `c b`, `c` and nothing with it. The hack crate stopped the third-party crates from compiling again; `c` and the members that depend on it still did. With the hack crate, every selection compiled `smallvec`, `x` and `y`, also `-p c`, which uses neither `smallvec` nor `y`.
2612
+ - **What cargo-hakari's commands report.** `cargo hakari verify` reported "workspace-hack works correctly" for each setup in the table, also while `x/funix` and the features of `c` and `z` followed the selection, and `cargo hakari generate --diff` passed. `verify` resolves each member with no, default and all features, with and without dev-dependencies, with the hack crate added, for the dependencies that hold on every platform and on each platform that the configuration lists, and checks third-party crates only (`hakari/src/verify/mod.rs`). Adding the host's triple to `platforms` without generating again made both commands fail.
2613
+ - **A stale hack crate.** With `b` asking for `x/fstale` and the hack crate not generated again, `generate --diff` printed the changed line and failed, `verify` failed, `manage-deps --dry-run` passed, and `x` had `fstale` with `-p a -p b` and not with `-p a`. With a new member `f` that asks for `x/fa` and has no dependency on the hack crate, `manage-deps --dry-run` failed and named `f`, while `generate --diff` and `verify` passed, and `cargo build -p f` compiled `x` with `fa` only. With `a` no longer asking for `x/fa`, so that the hack crate gave more than the members ask for, `generate --diff` failed, `verify` passed, and the features were the same in every selection. Each command reads the full package graph through `cargo metadata`: with an empty Cargo home and `CARGO_NET_OFFLINE=true`, `generate --diff` failed with "no matching package named `smallvec` found". cargo-hakari's documentation asks for `Cargo.lock` under version control, because a patch release of a dependency can change its features or dependencies (`cargo-hakari/src/lib.rs`).
2614
+ - **Finding the hack crate.** `cargo hakari init` wrote `.config/hakari.toml`, whose `hakari-package` names the hack crate, added that crate to `members`, and gave its `Cargo.toml` a generated part between `### BEGIN HAKARI SECTION` and `### END HAKARI SECTION`. `manage-deps` gave every other member a path dependency on it.
2615
+ - **The `cargo metadata` reports.** The `--no-deps` report lists the members only. Each dependency has `features`, `uses_default_features`, `optional`, `kind`, `target` with the `cfg(…)` expression or triple, `rename` and, for a path dependency, `path`, which for a dependency on a member is the member's folder. In a copy with a further member `e`, a dependency on `c` with `workspace = true` showed the features of `[workspace.dependencies]` and of `e` merged, a renamed optional one showed `rename` and `optional`, one under `cfg(windows)` showed that `target`, and `e`'s `features` table showed `c/fz`, `dep:cc` and `cc?/fa` as written. The report showed neither `z` nor what `z` asks of `c`. The full report also lists `z` with its dependency on `c` and `fz`, and its `resolve` gives each package the features of one resolution of the whole workspace with dev-dependencies, for all platforms: `c` had `cdef`, `default`, `fa`, `fb` and `fz`. On that copy with a warm Cargo home, the `--no-deps` report took 7 to 8 ms and the full report 18 to 21 ms. The full report needs every package's manifest, so without network in an empty Cargo home it fails ([[EVD-CARGO-NO-DEPS]]).
2616
+ - **Two workspaces that use cargo-hakari.** In shallow clones of guppy at `3f2cb12` and nextest at `8f2d970`, whose authors maintain cargo-hakari, `platforms` lists triples of Linux, macOS and Windows. Of the dependencies between members in their `--no-deps` reports, 10 of 26 in guppy and 3 of 15 in nextest ask for features of the other member or turn off its default features, such as `cargo-hakari` asking `hakari` for `cli-support` and `integration-tests` depending on `cargo-nextest` with `default-features = false`.
2617
+ - **The whole workspace without a hack crate.** With `d` also depending on `g`, a crate in a local git repository whose second commit asks for `smallvec`'s `const_generics`, `cargo update -p g` changed only the `source` line of `g` in `Cargo.lock`. The next `cargo build --workspace` compiled `smallvec` with `const_generics`, `union` and `write`, and compiled `a` again, though no package that `a` reaches changed in the lockfile and no member's manifest changed. Changing the feature that `z` asks of `c` from `fz` to `fa` made `cargo build --workspace` compile `c`, `z`, `a`, `b` and `d` again, and `a` printed `c` without `fz`.
2618
+ - **Flags that act on the selected crates.** Reruns on 14 November 2026 with cargo 1.100.0 and 1.91.0, which gave the same results, offline in an empty Cargo home, each selection built in an empty target directory and a crate's features read from its rustc line. In a workspace with resolver 2 and the members `a`, with the features `d`, `x` and `default = ["d"]`, `b`, with the features `x` and `y` and a dependency on `a` with default features, and `c`, with the feature `x` and no dependency on `a`: without flags, `a` had `default` and `d` with `-p a`, `-p b` and `-p a -p b`. With `--all-features`, it had `default` and `d` with `-p b`, and `default`, `d` and `x` with `-p a` and `-p a -p b`. With `--no-default-features`, it had none with `-p a`, and `default` and `d` with `-p a -p b` and `-p b`. With `--features x`, `a` had `x` with `-p a` and `-p a -p b` but not with `-p b` or `-p b -p c`, while `b` and `c` had `x` wherever selected; `-p b --features y` and `-p a -p b --features y` passed, giving `y` to `b` only. With `--features a/x`, `a` had `x` with `-p a`, `-p b`, `-p a -p b` and `-p b -p c`, and `-p c --features a/x` failed with "the package 'c' does not contain this feature: a/x". In a second workspace, where `c2` depends on `b` and `b` on `a` and on a crate `o` outside the workspace, `-p c2 --features a/x` and `-p c2 --features o/p` failed the same way, and `-p b -p c2 --features a/x` passed with `a` having `x`, so `crate/feature` needs a selected crate that is that crate or depends on it directly. With `resolver.feature-unification = "workspace"`, which the `cargo` strategy sets, and `-Zfeature-unification` with `RUSTC_BOOTSTRAP=1` on both versions, `a` had `default`, `d` and `x` with `-p b --all-features` and with `-p a -p b --all-features`, and `default` and `d` with `-p a --no-default-features` and `-p a -p b --no-default-features`, while `-p c2 --features a/x` and `-p b -p c2 --features x` still failed, the latter with "none of the selected packages contains this feature: x". Cargo applies `--all-features`, `--no-default-features` and unqualified names in `--features` to the selected crates only, and checks `crate/feature` against them; under workspace unification only `--features` still depends on the selection.
2619
+ - **Features that no manifest asks for.** Reruns on 14 November 2026 after an independent review of the design, with cargo 1.100.0 and 1.91.0 and workspace resolvers 2 and 3, all four giving the same results, offline in an empty Cargo home, each selection in an empty target directory, with the member `a` depending on the member `c` and `c` reporting `cfg!(feature = "default")` and `cfg!(feature = "t")`. With `default = []` in `c` and `default-features = false` in `a`'s dependency, `cargo build -p a` linked `a` with a `c` compiled without `default`, and `cargo build -p a -p c` with another `c`, under another `-C metadata` hash, compiled with `default`. With no `default` in `c`, both selections linked the same `c`. With `c` dev-depending on itself with `t` and `a` depending on `c` plainly, `cargo build` linked the same `c` in both selections, while `cargo check --all-targets` and `cargo test --no-run` linked `a` with a `c` without `t` under `-p a` and with `t` under `-p a -p c`.
2620
+ - **A sibling's lockfile change.** Also on 14 November 2026, with cargo 1.100.0 and 1.91.0: in a workspace with resolver 2 whose member `a` depends on the member `c`, and whose member `b` depends on `g`, a crate in a local git repository whose first commit asks `c = "0.1"` for `fx` and whose second asks for `fy`, with `[patch.crates-io]` giving `c` the member's path, `cargo update -p g --precise <commit>` from the first commit to the second changed only the `source` line of `g` in `Cargo.lock`, which `b` reaches and `a` does not. `cargo build --workspace` then compiled `c`, `g`, `a` and `b` again, and `a` printed `fy` where it had printed `fx`. Both lockfiles passed `cargo update --workspace --locked`.
2621
+ - **One command per crate.** With cargo-hakari 0.9.39, built for the experiment into a folder of its own, a workspace with `a` (`default = ["d"]`, `d`, and `x`, which asks `ext/e3`) and `b` (depending on `a` with default features), both depending on `ext`, a crate outside the workspace, with `e1` and `e2`, and a hack crate from `init`, `generate` and `manage-deps` with the host in `platforms`: the hack crate depended on `ext` with `e1`, `e2` and `e3`, so `generate` takes the features of every member's all-features build into account. On cargo 1.100.0 and 1.91.0, in one target directory `cargo build -p a --all-features` and then `-p b --all-features`, and in another the same commands in the other order, compiled `workspace-hack`, `ext`, `a` with all features, `a` with default features and `b` in both orders. `b` had the same `-C metadata` hash and linked the same `a`, with `default` and `d`, in both. Running the commands again compiled nothing. `cargo build -p a -p b --all-features` gave `b` another hash, linking `a` with `x`.
2622
+ - **Settings of the configuration.** With the same cargo-hakari, a workspace whose members `a` and `b` ask the crates `x`, `y`, `z` and `u` outside the workspace for different features, through normal, build and dev-dependencies, a `cfg(unix)` table and a crate that `a` uses as a normal dependency and `b` as a build dependency, and a hack crate with a build script, as `init` makes it. For each setting, `generate` and `manage-deps` ran, and `-p a`, `-p b` and `-p a -p b` were built with `cargo build` and `cargo test --no-run`, with `--target` naming the host so that the host's and the target's builds of a crate could be told apart. The configuration of `init`, `resolver = "1"`, `"3"`, the four values of `unify-target-host`, `output-single-feature = true` and an exclude of `b` were also built without `--target`, with the same outcome as with it. With the configuration that `init` writes and the host in `platforms`, every third-party crate had the same features in every selection, on the host and on the target. So it did with `resolver` set to `"1"`, `"2"` and `"3"`, in workspaces with resolver 1, 2 and 3, with `unify-target-host` set to `"none"`, `"auto"`, `"unify-if-both"` and `"replicate-target-on-host"`, with `dep-format-version` `"1"`, `"2"` and `"3"`, `exact-versions = true`, `output-single-feature = true`, and `workspace-hack-line-style` `"full"` and, with a `[workspace.dependencies]` entry for the hack crate, `"workspace-dotted"`. `verify` failed with `unify-target-host = "none"` and with `output-single-feature = true`, where the features were the same all the same. The features followed the selection with `final-excludes` naming `x` or the member `b`, and with `traversal-excludes` naming `y` or `b`, where `generate --diff` and `verify` passed; and with `workspace-hack-line-style = "version-only"`, which gave the members `workspace-hack = { version = "0.1" }` without a path, where both passed as well. `registries` was not tried. A third-party crate is named in an exclude by its name and, for a path crate, its path relative to the workspace root.
2623
+ - **The configuration.** Read in the sources of cargo-hakari 0.9.39 and hakari 0.18.0 on 14 November 2026: cargo-hakari reads `.config/hakari.toml` in the workspace root and, where that is missing, `.guppy/hakari.toml` (`DEFAULT_CONFIG_PATH` and `FALLBACK_CONFIG_PATH`, `hakari/src/summaries.rs`; `make_builder_and_output`, `cargo-hakari/src/command.rs`). Beside `hakari-package`, `resolver` and `platforms`, the configuration has `unify-target-host`, and `traversal-excludes` and `final-excludes`, each with `workspace-members` and `third-party`, which leave packages out of the traversal and out of the hack crate (`HakariBuilderSummary`, `hakari/src/summaries.rs`; `add_traversal_excludes` and `add_final_excludes`, `hakari/src/hakari.rs`). Every command builds the package graph with guppy's `MetadataCommand` without a manifest path or other options, so it passes cargo no `--locked` or `--offline`, and cargo-hakari takes neither flag (`Command::exec`, `cargo-hakari/src/command.rs`).
2624
+ - **Without the hack crate.** On 16 November 2026 with cargo 1.100.0 and cargo-hakari 0.9.39, in a workspace whose members `a` and `b` depend on the hack crate that `init`, `generate` and `manage-deps` made: `cargo build -p a --config "patch.'file://<workspace>/workspace-hack'.workspace-hack.path='<empty crate>'"`, with an empty crate of the hack crate's name and version, failed with "failed to select a version for `workspace-hack`" and "all possible versions conflict with previously selected packages", naming the member: a `[patch]` on the command line cannot put another crate in place of a member. `Cargo.lock` stayed as it was.
2625
+ - **What cargo-hakari 0.9.39 generates for a git dependency.** In a workspace whose members `a` and `b` ask a crate `x` of a local git repository for `f1` and `f2`, with the host in `platforms`: the hack crate's hakari section held `x = { git = "file://…", default-features = false, features = ["f1", "f2"] }`, after the header, package table and comments that `init` writes, and its folder held `build.rs`, `src/lib.rs` and a `.gitattributes`; `generate --diff` and `manage-deps --dry-run` passed on it and on the same files written by the tests' harness, and `cargo build -p a` and then `cargo build -p a -p b` compiled `x` once, `a` printing `f1 f2` after both. With `b` asking `x` for no feature, `generate --diff` exited with 1; with the dependency of `a` on the hack crate removed, `generate --diff` exited with 0 and `manage-deps --dry-run` with 1, and with 0 again after `manage-deps -y`. Cargo 1.100.0 also warned that the members' dependency on the hack crate was unused (`cargo::unused_dependencies`), which changes no result.
2626
+
2627
+ So the hack crate makes the features of third-party crates the same in every selection for normal, build and dev-dependencies, and for platform-specific dependencies only on the platforms that its configuration lists. It leaves the features of members, and of third-party crates that depend on a member through normal or build dependencies, to the selection, and `cargo hakari verify` reports neither. The `--no-deps` report shows what one member asks of another, not what a crate outside the workspace asks of a member. Cargo's `--all-features`, `--no-default-features` and `--features` act on the selected crates, and a command that selects one crate gives a member that is only its dependency what its dependents ask. Excludes and `version-only` in cargo-hakari's configuration leave features to the selection, without `generate --diff` or `verify` noticing. The points marked with a source file were read, not run.
2628
+ :::
2629
+
2630
+ :::mara evidence EVD-HAKARI-PUBLISHING
2631
+ :mid: 01M7JRNDYF9P89B48NFK03QP5M
2632
+ :title: What cargo-hakari 0.9.39 writes that publishing depends on
2633
+ :status: accepted
2634
+ :supports: DES-RELEASE
2635
+
2636
+ A run on 16 November 2026 on Linux x86-64 with cargo 1.100.0 and cargo-hakari 0.9.39, in a throwaway Cargo workspace outside this repository with the members `a` and `b`, `a` depending on `b` with `path` and `version`, a git repository and resolver 2, with a Cargo home of its own and `CARGO_NET_OFFLINE=true`, so that nothing reached a registry. Each step started from the committed state.
2637
+
2638
+ - **The hack crate.** `cargo hakari init workspace-hack --yes` wrote `.config/hakari.toml` with `hakari-package = "workspace-hack"`, `dep-format-version = "4"` and an empty `platforms`, added `workspace-hack` to the members of the root manifest, and wrote `workspace-hack/Cargo.toml` with `publish = false` under the comment "You can choose to publish this crate: see https://docs.rs/cargo-hakari/latest/cargo_hakari/publishing", beside `version = "0.1.0"` and `description = "workspace-hack package, managed by hakari"`. `cargo hakari generate` changed only the part between `### BEGIN HAKARI SECTION` and `### END HAKARI SECTION` and kept `publish = false`.
2639
+ - **The members' dependency.** `cargo hakari manage-deps --yes` added to the `[dependencies]` table of every member other than the hack crate, also of a member with `publish = false`, one entry: under `dep-format-version = "1"` `workspace-hack = { path = "../workspace-hack"}`, without a version requirement; under `"2"`, `"3"` and `"4"` `workspace-hack = { version = "0.1", path = "../workspace-hack" }`. Under `"4"` it wrote that entry in the member's own table also where `[workspace.dependencies]` of the root manifest held `workspace-hack` with `version` and `path`, not `workspace = true`. It writes no `registry` key, so the entry points to crates.io ([[DES-RELEASE]], **Where a dependency points**).
2640
+ - **Publishing.** `cargo hakari publish --help` says "Publish a package after temporarily removing the workspace-hack dependency from it", takes one package with `-p` and passes trailing arguments to `cargo publish`; [[EVD-CARGO-PUBLISH]] records what it does around the call from its sources.
2641
+
2642
+ So under the default dep-format, every member depends on the hack crate with a version requirement and the hack crate sets `publish = false`, which the check _Unpublished dependencies_ of [[DES-RELEASE]] then fails for every member that is published; under dep-format 1, cargo refuses such a member itself, because a normal dependency without a version requirement cannot be published ([[EVD-CARGO-PUBLISH]]).
2643
+ :::
2644
+
2645
+ :::mara evidence EVD-CARGO-BATCH-FAILURES
2646
+ :mid: 01M7DC64QCDZKPH44D2YB14XD7
2647
+ :title: What cargo reports per crate when one command serves several crates and one of them fails
2648
+ :status: accepted
2649
+ :supports: DES-BATCH
2650
+ :supports: DES-TEST-RUN
2651
+
2652
+ Experiments on 14 November 2026 on Linux x86-64 with cargo 1.100.0, the central cases repeated with cargo 1.91.0, in throwaway workspaces outside this repository, with `RUSTUP_AUTO_INSTALL=0`. The first workspace had the members `base`, `dep`, which depends on `base`, `broken`, `indep`, with a library, a binary and an integration test, `user`, which depends on `broken`, and `scripted`, whose build script panics when an environment variable is set.
2653
+
2654
+ - **A compile error stops a test run.** With a unit test of `broken` that does not compile, `cargo test --workspace --no-fail-fast` exited with 101 after "could not compile `broken` (lib test)" and ran no test of any crate. With the library of `dep` not compiling, `cargo test --doc --no-fail-fast -p base -p dep -p indep` ran no doctest. `cargo test --keep-going` and `cargo test --no-run --keep-going` were rejected as unknown arguments.
2655
+ - **`--keep-going` in builds.** With the library of `broken` not compiling, `cargo build --workspace --message-format=json -j 1` stopped after `broken`: it had built only the build script of `scripted`. With `--keep-going`, it built `base`, `dep`, `indep` with its binary and `scripted`, and reported nothing for `user`. `cargo check --workspace --all-targets --keep-going`, with a unit test of `broken` not compiling, built every other target, the unit test of `user` included, which needs only the library of `broken`. With cargo 1.91.0, `build`, `check` and `clippy` with `--keep-going` gave the same targets.
2656
+ - **What the JSON messages show.** Each target that cargo built gave a `compiler-artifact` message with its package id and target, with `fresh` set where nothing was compiled. A rustc error gave a `compiler-message` at level `error` with the package id and target, and `build-finished` reported `success: false`. With the build script of `scripted` panicking, `cargo build --keep-going` and `cargo check --all-targets --keep-going` gave an artifact for the compiled build script and none for the library of `scripted`, and no error message and no `build-script-executed` for it. Only the human-readable "failed to run custom build command for `scripted v0.1.0 (…)`" on stderr named it.
2657
+ - **Which package a test result belongs to.** A second workspace had the members `good`, `other`, whose library is also named `good`, `third` and `fourth`, under `crates/`; the unit test and the doctest of `other` and of `third` failed. `cargo test --doc --no-fail-fast -p good -p other -p third -p fourth` printed `Doc-tests fourth`, `Doc-tests good` twice and `Doc-tests third` on stderr, and the test lines on stdout with paths from the workspace root, such as `test crates/other/src/lib.rs - one (line 1) ... FAILED`. After each failing block it printed "doctest failed, to rerun pass `-p other --doc`", and at the end "2 targets failed:" with `` `-p other --doc` `` and `` `-p third --doc` ``. `cargo test --no-fail-fast` printed `Running unittests src/lib.rs (…/good-<hash>)` for both `good` and `other`, and listed `-p other --lib`, `-p third --lib`, `-p other --doc` and `-p third --doc`. With one failing target the list read "1 target failed:". Without `--no-fail-fast`, cargo stopped after the doctests of `other` and printed no list. cargo 1.91.0 printed the same lines. Its unit-test binaries lay in `target/debug/deps`, while those of 1.100.0 lay in a folder per package under `target/debug/build`.
2658
+ - **Units compiled as tests.** In a third workspace, the member `a` had a library with a unit test, a binary, an example, an integration test, a bench without harness and a dev-dependency on the member `brokendev`. `cargo check --all-targets --message-format=json -p a` reported the library, the binary and the example with `profile.test` off, and the library, the binary, the integration test and the bench with it on, with cargo 1.100.0 and 1.91.0; `clippy --all-targets` reported the same units. With the library of `brokendev` not compiling, `cargo check --all-targets --keep-going --message-format=json -p a -p c` reported the library and the binary of `a` with `profile.test` off, nothing of `a` with it on, and no error for `a`, while `cargo check --all-targets -p a` alone failed. `test = false` on the library kept its test unit while its `bench` flag stayed on, and `test = false` with `bench = false` left it out; the binary behaved the same. `test = false` on the integration test left it out, `test = true` on the example added its test unit, and `bench = false` on the bench left the bench out. The `cargo metadata` report gives each target's `test` flag and not its `bench` flag. Without `--all-targets`, `build` and `check` reported the library and the binary with `profile.test` off only.
2659
+ - **Package names.** Two members named `same` made `cargo metadata` fail with "two packages named `same` in this workspace". With a member `good` 0.1.0 and a path dependency `good` 0.2.0 outside the workspace, `-p good` failed with "specification `good` is ambiguous", while `-p good@0.1.0` worked. The failure list named the member by its bare name, `` `-p good --doc` ``. Which selections are ambiguous, and the form that never is, are in [[EVD-CARGO-PACKAGE-SPECS]].
2660
+ - **The selection decides the features.** In a workspace where the member `b` asks for the feature `x` of the member `shared` and `a` does not, `cargo test --doc -p a` compiled `shared` and `a` again after `cargo test --no-run --workspace`. After another `cargo test --no-run --workspace`, `cargo test --doc --workspace` compiled nothing.
2661
+
2662
+ So with `--keep-going`, which `cargo test` does not have, cargo builds as much as it can. Its JSON messages show what it built, unit by unit, a target in normal mode and compiled as a test apart, but not every failure. The list of failed targets that `--no-fail-fast` prints identifies the package of a failing test, and the block headers do not. A further step that selects other crates resolves other features. That nextest builds every test binary before it runs one was read in its documentation when this item was written; [[EVD-WORKSPACE-TEST-SELECTION]] ran it with cargo-nextest 0.9.152 on both versions, and the run stopped before any test.
2663
+ :::
2664
+
2665
+ :::mara evidence EVD-CARGO-ARTIFACT-WRITERS
2666
+ :mid: 01M7DJ8QGMBPJSJHQ2BVBCHA1R
2667
+ :title: Which cargo calls replace the executables that build stores, and what Nx stores when they run beside it
2668
+ :status: accepted
2669
+ :supports: ADR-TEST-AFTER-BUILD
2670
+ :supports: DES-TARGETS
2671
+ :supports: DES-OUTPUTS
2672
+ :supports: DES-BATCH
2673
+ :supports: RISK-ARTIFACT-DIR-WRITERS
2674
+
2675
+ Three sets of experiments on 14 November 2026, on Linux x86-64 with 32 cores, `nx` 24.0.6, Node.js 26.12.0, cargo 1.100.0 and, where named, 1.91.0, `RUSTUP_AUTO_INSTALL=0`, the Nx daemon off, a private `NX_CACHE_DIRECTORY` and the variables by which Nx detects an AI agent removed, in throwaway workspaces outside the repository. The research for nxr-1q1f0n (the research below) used the plugin compiled from `main` at 3445ae7 and stand-ins for the edge, a lock, a copy and batch executors. The work on nxr-621hvq (mine below) used the plugin compiled from `main` at 96ba5f0, without the edge, and from the change that adds the edge and its guard, on a machine whose load average was about 4 from other work. The work on nxr-ew8kb3 (**Files of one name** below) used the plugin compiled from the change that leaves such builds uncached, on `main` at ae3fd4c, with the rule in place and taken out, on a machine whose load average was about 30 from other work. In each workspace, crate `a` has a binary that prints `FLAVOUR-EXTRA` where the feature `extra` of its path dependency `f` is on and `FLAVOUR-PLAIN` otherwise, and turns `extra` on through a dev-dependency on `f`.
2676
+
2677
+ **What writes the executables of `build`.** Mine, on 1.100.0 and 1.91.0 alike, with a binary crate of each shape, `cargo build -p` and then `cargo test -p`, comparing the inode of `target/debug/<bin>`:
2678
+
2679
+ | The crate has, besides its binary | `cargo test -p` replaces the executable |
2680
+ | ------------------------------------------------------------------------------------- | --------------------------------------- |
2681
+ | An integration test in `tests/`, also one that names no `CARGO_BIN_EXE_` | Yes, with `FLAVOUR-EXTRA` |
2682
+ | A `[[test]]` with `harness = false` | Yes |
2683
+ | A `[[bench]]` with `test = true` | Yes |
2684
+ | A `[[bin]]` with `test = false`, and an integration test | Yes |
2685
+ | An example, also one with `test = true` | No |
2686
+ | Unit tests only, or a library with doctests | No |
2687
+ | A `[[test]]` with `test = false` | No |
2688
+ | A `[[bench]]` without `test` | No |
2689
+ | `autotests = false` and a file in `tests/` | No |
2690
+ | A binary with `required-features`, or an integration test with them, the features off | No; with `--features` on, yes |
2691
+
2692
+ The `--no-deps` report gives each target its `kind` and a `test` flag on both versions, and no `bench` flag: the replacing crates are exactly those with a target of kind `bin` and a target of kind `test` or `bench` whose `test` flag is on, apart from the `required-features` cases, which depend on the features of the run. A `cargo build -p` afterwards put back the executable that prints `FLAVOUR-PLAIN`, a new inode, although its unit was fresh; a second `cargo test -p` left a file that already was its own alone. `cargo test` left the binary's dependency file `<bin>.d` as `cargo build` wrote it. The research found the same for the shapes it tried, and that `cargo bench` replaces `target/release/<bin>` for a `[[bench]]`; that `[profile.test] opt-level = 1` alone makes the executables differ; that `cdylib` and `staticlib` files, `check`, `clippy` with and without `--all-targets` and `doc` leave the files of `build` alone, that only `doc` writes the `doc` folder, and that `cargo run` writes the bytes of `build` where its options match; that `CARGO_BIN_EXE_<bin>` is the uplifted path itself, and that `cargo test` releases the build lock before it runs the test executables, so that a `cargo build -p` started then replaced the file the tests were about to run; and that two crates whose binaries have one name write one file, cargo warning of an output filename collision where one call builds both.
2693
+
2694
+ **When Nx stores.** The research: Nx copies a task's outputs in `postRunSteps` after its process has ended (`tasks-runner/task-orchestrator.js`, lines 1132 to 1221, `cache.put` at line 1850); the copy was born 21 to 27 ms after the cargo process of `build` exited. It awaits the copy before it completes the task and schedules the tasks that depend on it (lines 1850 and 1873 to 1874). Every wrong entry had the crate's `cargo test` replace the file within that gap.
2695
+
2696
+ **Without the edge, then with it.** The research, with six such crates, a warm build directory and an empty Nx cache, `nx run-many -t build test` at the default parallelism: 16 of 36, 8 of 24 and 13 of 29 `build` entries held `FLAVOUR-EXTRA` in three series; 4 of 18 with `--parallel=6`; none with `--parallel=1`, after `cargo clean`, after an edit of one crate, or for one crate alone. With the edge simulated by a `project.json`, none of 30. With one crate whose integration test waits 1.5 s and then runs its executable, `nx run-many -t build test -p a` failed `a:test` in 5 of 5 and 4 of 4 runs where `cargo test -p a` passes, and passed 4 of 4 with the edge.
2697
+
2698
+ Mine, with the real implementation: six such crates whose integration tests run the executable at once and expect `FLAVOUR-EXTRA`, the build directory warmed by plain `cargo build` and `cargo test --no-run`, and before each run an empty Nx cache and no `.nx` folder, as in a fresh CI checkout; `nx run-many -t build test` at the default parallelism, three series of six runs:
2699
+
2700
+ | Plugin | `build` entries with `FLAVOUR-EXTRA` | Failed `test` tasks |
2701
+ | ----------------------------- | ------------------------------------ | ------------------- |
2702
+ | From `main`, without the edge | 12, 8 and 12 of 36: 32 of 108 | 1 of 108 |
2703
+ | With the edge and its guard | 0 of 108 | 0 of 108 |
2704
+
2705
+ With the edge, the `cargo test` of each crate started 93 to 461 ms after the `cargo build` of the same crate had exited, in 116 of 116 calls of these runs and of the next ones; without it, 32 of 116 started before. With one crate whose test waits 1.5 s, `nx run-many -t build test -p a1` failed `a1:test` in 8 of 8 runs without the edge and in none of 8 with it. Over all projects of that workspace instead of `-p a1`, none of 4 failed either way: Nx happened to start `a1:build` first. With the `.nx` folder kept from earlier runs and integration tests that wait 1 s, 2 of 108 entries were wrong without the edge: Nx orders runnable tasks by the timings that it recorded (`tasks-runner/tasks-schedule.js`, `sortScheduledTasks`) and ran the slow tests before the builds. How often the wrong case happens therefore depends on Nx's history and the machine's load; with the edge it did not happen at all.
2706
+
2707
+ **Batches.** The research, with stand-in batch executors that ran one cargo call per kind of task over the six crates and the edge in place: with one executor for both targets, Nx put each crate's `build` and `test` into one batch, because it adds a task's dependents of the same executor (`tasks-runner/tasks-schedule.js`, lines 180 to 188), stored at its end, and 12 of 12 `build` entries were wrong for `-t build test` and for `-t test`; with `build` on one executor and `test` on another, the `build` batch ran and was stored before the `test` batch started, because the coordinator awaits a batch, storing included (`task-orchestrator.js`, lines 329 to 339 and 739 to 780), and none of 12 was wrong.
2708
+
2709
+ **`bench` and other orderings.** `bench` has `parallelism: false`. Nx's `canBeScheduled` starts such a task only when no other task runs and starts no task while it runs (`tasks-schedule.js`). Mine: six runs of `nx run-many -t build test bench check lint fmt-check` over seven crates, one of them with a bench that takes 3 s, three with `--parallel=3` and three with `--parallel=8`: none of the 58 other cargo calls of a run overlapped the one of `cargo bench`. Read, not run: `canBatchTaskBeScheduled` does not look at running tasks, but the coordinator runs a batch before it dispatches single tasks, and while a `parallelism: false` task runs it schedules again only when a task completes or a continuous task's readiness is settled, so a batch can start beside such a task only through a readiness verdict. Nx gives a dependency the configuration of the command where its target has it, and its target's default configuration otherwise (`tasks-runner/create-task-graph.js`, `resolveConfiguration`), so the `build` that the edge reaches is the `build` that the same command names. Continuous dependencies, read and tried by me: Nx keeps them apart from the ordinary ones, records every edge into a continuous task as continuous (`addContinuousEdge`), and schedules a task, continuous ones included, only when its ordinary dependencies have completed, which `complete()` records after their outputs are stored, and its continuous dependencies are running, or ready where a probe or `waitFor: "ready"` asks for it (`tasks-schedule.js`, `canBeScheduled` and `areContinuousDependenciesReady`). With the edge's guard taken out and the `cargo build` of `app:build` held, a `test` that depended on a continuous helper without dependencies started its `cargo test` while the build was held, and one whose helper depended on `build` started it only after the build; with the guard in, the second passed and the first failed, and so did a `test` whose `build` was itself continuous, in three of three runs. The research found that `--exclude-task-dependencies` keeps the edges between the tasks that a command names (lines 53 to 66), and that a `test` cache hit still waits for `build` to run or be restored.
2710
+
2711
+ **What the edge costs.** The research, toy crates: `nx run a:test` alone took 520 to 550 ms without the edge and 670 to 680 ms with it on a warm build directory and an empty cache, 450 to 470 against 490 to 500 ms on a cache hit, and 631 against 887 ms on a cold build directory, where `f` and `a` were each compiled twice; for a crate whose dev-dependencies change nothing, `cargo test` reused the unit of `build` (`fresh: true` in its messages), and the edge cost one task and no compilation.
2712
+
2713
+ **The alternatives.** The research: a lock held by every `build` and `test` cargo call for its whole duration left 10 of 30 entries wrong, since Nx copies after cargo exits, and let all 4 test runs pass. A copy that `build` links into a folder of the plugin right after cargo exits left 1 of 30 wrong, none while the lock is held, and a cache hit restored only that folder. A private artifact folder over the shared build directory, `CARGO_BUILD_BUILD_DIR` shared and `CARGO_TARGET_DIR` private, failed beside plain cargo on 1.91.0 and 1.100.0: after plain `cargo test -p a`, the private call, an edit of the binary from `V1` to `V2` and the private call again, cargo compiled only the binary, the test executable stayed fresh, `env!("CARGO_BIN_EXE_a")` still named the shared folder and the test ran the old `V1`; and the other way round after the private call first.
2714
+
2715
+ **Files of one name.** On 1.100.0 and 1.91.0 alike unless named. In one workspace with a binary called `cli` in three crates, through a `[[bin]]` table, through `src/bin/cli.rs` and as the binary of a package called `cli`, `cargo build` warned of an output filename collision at `target/debug/cli` and `target/debug/cli.dwp` for each pair, 1.100.0 in a new layout of the message, and the file was that of one of the crates, another one in different runs; each `cargo build -p` afterwards put its own crate's executable there, a new inode each time, although its unit was fresh. In one of 16 such workspace builds with 1.91.0, and in none of 16 with 1.100.0, a crate's own unit in `deps` held another crate's executable afterwards, so that `cargo build -p` of that crate put the other's executable in place. A binary called `Cli` beside them drew no warning and got a file of its own on Linux. A binary called `libuni.so` failed in rustc, which refuses a `.` in a crate name, and binaries called `café` and `CAFÉ` built. Cargo warned in the same way for two `cdylib` libraries of one name, one of them also an `rlib`, for two `staticlib` libraries, and for a `cdylib` beside a `dylib` and beside a proc macro of its name, 1.91.0 also for the files of the `cdylib` and the `dylib` in `deps`; it refuses a library that is both a `dylib` and a `cdylib`. `cargo build -p` of each of these crates wrote the file, and so did `cargo build -p` of a crate that depends on the `dylib`, while one of a crate that depends on the proc macro wrote none. Two Cargo workspaces and a standalone crate whose binaries are all called `cli`, given one artifact directory by `build.target-dir` in a `.cargo/config.toml` above them or by `CARGO_TARGET_DIR`, each wrote `target/debug/cli`, without a warning, since no call built two of them, and the same in `target/release` and, with 1.100.0, in the folder of `--target x86_64-unknown-linux-musl`, for which 1.91.0 had no standard library installed. `CARGO_BIN_EXE_cli` in a crate's integration test named `target/debug/cli`; the test, which waits 1.5 s and then expects its own crate's output, passed alone and failed with the other crate's output where `cargo build -p` of the other crate started 0.7 s after `cargo test -p`. With Nx, in the fixture `shared-executables`, with a build directory warmed by plain `cargo build -p` of `alpha` and `beta`, an empty Nx cache and no `.nx` folder before each run, `nx run-many -t build -p alpha beta` at the default parallelism, and then for each of the two crates the executable deleted and `nx run <crate>:build`: with the rule taken out, Nx restored every entry, and 7 of 16 held the other crate's executable, 5 of 8 for `alpha` and 2 of 8 for `beta`; with the rule, all 16 ran cargo and left their own crate's executable.
2716
+
2717
+ **Files of one name across entries and nested directories.** The review of nxr-ew8kb3 found two configurations that the first comparison missed: two entries of the plugin in `nx.json`, one for each workspace, whose workspaces share an artifact directory, and one workspace's artifact directory set to the folder of a triple in another's, where a `build` for that triple writes the other's path. In the fixture `shared-executables`, with the change that compares the workspaces of every entry and counts nested directories, and with each part taken out in turn: without the other entries' workspaces, both crates' `build` stayed cached, with plugin isolation on and off, and a second `nx run-many -t build` restored both; without nested directories, the same for the triple's folder; with both parts, both builds ran in every run and each left its own executable. Graph creation of that fixture, two workspaces, five runs each on a machine whose load average was about 50: with one entry, 2 `cargo metadata` calls, medians of 545 and 586 ms with plugin isolation and 230 and 242 ms without; with two entries, 2 calls without plugin isolation, where the entries share their reports, and 4 with it, one more per workspace of the other entry in each worker, medians of 550 ms with the comparison and 637 ms without it, and 235 and 263 ms without isolation, within the spread of the runs.
2718
+
2719
+ **A second installation and overlapping entries.** The second review of nxr-ew8kb3 found that a second installation of the plugin, registered under another name for one workspace, is not taken for an entry of the plugin, so that graph creation leaves the build of the plugin's crate cached and a held run stored the other crate's executable under its key, on Cargo 1.100.0 and 1.91.0 with plugin isolation on and off. In the fixture `shared-executables`, with a copy of the compiled plugin installed as the package `rust-alias` and registered under that name for `tools/`, beside the plugin's entry for `rust/`, both builds stayed cached; with the check when the task starts, `alpha:build`, `alpha:test` and `tools:build` failed before cargo ran and the builds of `beta` and `gamma` ran and were restored; without the check, `alpha:build` ran and succeeded. The check took 2.64 µs a task, over 19 cached `build`, `doc` and `test` tasks of `release-crates`, the largest fixture with 18 projects, in 2,000 rounds, and found no pair in any fixture. With two entries that both receive `rust/` (the plugin's name, and the plugin with `include` of `rust/**`), Nx 24.0.6 joins the lists that both give a project (`mergeMetadata` in `target-merging.js`): before the change, `metadata.cargo.warnings` held the warning twice and `nx show projects` printed it twice, with plugin isolation on and off; target metadata such as `triples`, `digests`, `members` and Nx's own `technologies` held their entries two to nine times, while `gamma:build`, `gamma:check` and `beta:test` passed. `cargo doc` of a workspace with two binaries called `cli` failed on 1.100.0 and 1.91.0 with a document output filename collision, and passed with `doc = false` on one of them.
2720
+
2721
+ So within one command, ordering `test` after the crate's own `build` keeps every stored `build` entry and every `test` result right on this workload, and a batch keeps them right only where `build` runs in a batch of its own. The experiments used small path crates on one machine; macOS, other Nx versions, nextest and real dependency trees were not tried.
2722
+ **Commands that select the whole workspace.** Run on 15 November 2026 for nxr-8f9dz2 with cargo 1.100.0, in a copy of the `binary-tests` fixture outside the repository, after `cargo build -p app`: `cargo test --workspace --exclude app --no-run` and `cargo test -p library --no-run` left `target/debug/app` as `cargo build` wrote it, and `cargo test --workspace --no-run` replaced it with another file, whose SHA-256 differed, as `cargo test -p app` does. Then, with cargo 1.100.0 and 1.91.0 alike, after `cargo build --workspace` in another copy, `cargo test --workspace --no-run` replaced exactly the files `app`, `benched` and `harnessless` of `target/debug` with others, and left `libaddon.so`, `libaddon.a`, the libraries' `rlib` files and the executables of `showcase`, `timed`, `unit` and `untested` as `cargo build` wrote them; `cargo test --workspace --tests --no-fail-fast` and `cargo test --workspace --doc --no-fail-fast` after it changed no file's content further. `gated`, whose binary needs a feature, was not built. A `cargo test` that selects the whole workspace, as the steps of `workspace-build` do ([[DES-TEST-RUN]]), therefore writes the executables that the `build` of every crate of the workspace with a binary and an integration test or a bench that `cargo test` builds stores, not only those of the crates of its group, and no other file that a `build` declares.
2723
+
2724
+ **Feature sets of one crate.** Run on 16 November 2026 for the review of nxr-8f9dz2, with cargo 1.100.0 and 1.91.0 alike, in a throwaway workspace whose members are `a`, a binary with a feature `extra` that it prints; `b`, a binary whose feature `extra` turns on the features `extra` of its path dependencies `c`, `d` and `e`; `c`, a library with the crate types `cdylib` and `rlib`; `d`, one with `staticlib` and `rlib`; and `e`, a library with a binary `e-tool`. After `cargo build --workspace`, the files directly in `target/debug` were listed with their modification times, and after `cargo build -p b --all-features` one second later, only `b` and `b.d` had been written: `a`, `libc.so`, `libd.a`, `e-tool` and their dependency files kept their times, though `b`'s feature set compiled `c`, `d` and `e` again with other features, and `a` still printed `plain`. A command that selects one crate writes the files of that crate alone: a dependency is built as a library, without its `cdylib`, `staticlib` or binaries.
2725
+ :::
2726
+
2727
+ :::mara evidence EVD-BATCH-FILES-ON-DISK
2728
+ :mid: 01M7WVPS52WX44QPGQDNT5PQM5
2729
+ :title: What a later cargo command of a batch does to the files that a task outside the batch reads, and what keeping them changes
2730
+ :status: accepted
2731
+ :supports: DES-BATCH
2732
+ :supports: RISK-ARTIFACT-DIR-WRITERS
2733
+
2734
+ Runs on 20 November 2026 for nxr-yfh7zh, with `nx` 24.0.6, Node.js 26.12.0 and cargo 1.100.0 on Linux x86-64 with 32 cores, through the test harness, without the Nx daemon where not named and with a private cache, and a reading of that Nx package (paths under `dist/src/`). The fixtures were copies of `workspace-tests` with the binary crates `pa` and `pb` of [[VER-BATCHING]], whose builds differ in environment through `pb`'s `.env`, and of `binary-tests`, where `cargo test` links `app` with a feature that `cargo build` leaves off. A cached JS target `pack` depended on `pa:build`, or `app:build`, with that crate as an implicit dependency and the inputs `default` and `^default`, and wrote what the executable printed into `dist`, as in the reviewer's reproduction ([[EVD-NX-24-BATCHES]], "Tasks left out"). Each run was made with the plugin as on `main` and with the first remedy of nxr-yfh7zh, commit 41c2299, which kept the files of the command's other builds and put them back after each later group, and which [[ADR-STAGED-BUILDS]] replaced:
2735
+
2736
+ | Run | `pack` stored, as on `main` | With the files kept |
2737
+ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- | ----------------------------------------------------------- |
2738
+ | `nx run-many -t build pack -p pa pb pack --parallel=3`, `pb`'s group left for a second wave | `plain flag` | `plain` |
2739
+ | The same after `nx run pa:build`, so that Nx restored `pa` and the batch ran only `pb`'s whole-workspace build, leaving no task out | `plain flag` | `plain` |
2740
+ | The first run with `NX_DAEMON=true` | `plain flag` | `plain` |
2741
+ | `nx run-many -t build test pack -p app pack`, `pack` depending on `app:build` and `app:test`, so that it runs after the `test` batch | `extra`, from `cargo test` | `extra`; `plain` where the `test` groups keep the files too |
2742
+ | `nx run-many -t build pack -p pa pb pack --batch=false --parallel=1`, `pack` depending on both builds | `plain flag` | `plain flag` |
2743
+
2744
+ After each wrong batched run, deleting `dist` and running `nx run pack:pack` restored `plain flag` beside a restored `pa` that printed `plain`, with the daemon too: its record of `pa:build`'s outputs no longer matched the file that `pb`'s build had linked, so that Nx copied `pa` from the cache in the later command (`shouldCopyOutputsFromCacheBatch` in `tasks-runner/task-orchestrator.js`). Within a command, Nx restores a task only before it runs it, as the waves of a batch do for the tasks that they look up (`applyCachedResults`, line 678), never one that has ended, and a batch's result has a status, a terminal output and times and no outputs (`TaskResult` in `config/misc-interfaces.d.ts`). No report of the batch and no order of its waves therefore has Nx put a file back: any order leaves one build's links last, and the restored case has a single wave. With batching off, `--parallel=1` and `pack` depending only on `pa:build`, Nx ran `pack` before `pb:build` in one run, storing `plain`, and after it in another, storing `plain flag`; a task run on its own keeps no files.
2745
+
2746
+ A `test` of `pa` whose integration test asserts that `CARGO_BIN_EXE_pa` prints `plain` passed in `nx run-many -t build test -p pa pb` after both waves: the plugin's own tasks read these files only through cargo, which links again what its command runs, and `napi-build`'s post-processing reads the library that its own compile reported (read, not run). Within one batch process, no group writes another's stored files: two whole-workspace `build` groups of one workspace root never both run there, and a group that selects crates writes only theirs ([[DES-BATCH]], "Files that a batch stores"). The case therefore needs a build that ended before the batch process, in an earlier wave or restored, or a `test` or `bench` batch after the builds.
2747
+
2748
+ That first remedy kept the files in groups of `build`, `napi-build` and `wasm-build`. Keeping them in the groups of `test` as well, which was tried, stored `plain` in the fourth row, but left the artifact directory with the executables of `cargo build` after `nx run-many -t build test`, where [[ADR-TEST-AFTER-BUILD]] accepted those of `cargo test`, as plain cargo leaves them, and 9 tests of that choice failed (nxr-5hzxra). With the files kept by that remedy, no second name was left in the artifact directory after any run, and plain `cargo build --workspace` with `pb`'s flags afterwards compiled nothing and linked `pa` again with the flag. The runs on `main` were reproduced with the keeping switched off, under which the batched cases of `nx-rust/test/batch-deferral.spec.ts` fail. The fixtures had two or three small crates; macOS, other Nx versions and real dependency trees were not tried.
2749
+
2750
+ Runs on 21 November 2026 for nxr-5hzxra, with the same Nx and Node.js and cargo 1.100.0, through the test harness, with `test` and `bench` groups keeping the files of the command's builds ([[DES-BATCH]], "Files that a test batch puts back"): in `binary-tests` with `pack` depending on `app:build` and `app:test`, `nx run-many -t build test pack` stored `plain` for `pack`, the integration test passed against the executable of `cargo test`, and afterwards `app` printed `plain` and no second name was left; `nx run pack:pack` without `dist` restored `plain` beside an `app` that printed `plain`. Plain `cargo test --workspace --no-run` afterwards compiled nothing and left `app` printing `extra`, having linked its uplifted file into place again, as it does after plain `cargo build`, and plain `cargo build --workspace` then compiled nothing and left it printing `plain`. The group of the whole workspace kept the nine files of the builds that the fixture stores, the `cdylib` and `staticlib` of `addon` among them, under second names beside them. That was the implementation at commit c08c014, which expanded each build's outputs into files; the review replaced it with the candidates of [[DES-BATCH]] and a stage, under which the same group keeps the executables of `app`, `benched` and `harnessless` (`nx-rust/test/test-after-build.spec.ts`).
2751
+ :::
2752
+
2753
+ :::mara evidence EVD-STAGED-BUILDS
2754
+ :mid: 01M7X59APKVHDRKGF3ZJ3EYWB9
2755
+ :title: What building into a stage of cargo's own does, on cargo 1.91.0 and 1.100.0 and through Nx 24.0.6
2756
+ :status: accepted
2757
+ :supports: ADR-STAGED-BUILDS
2758
+ :supports: DES-BATCH
2759
+ :supports: DES-BUILD-DIRS
2760
+ :supports: DES-OUTPUTS
2761
+ :supports: REQ-CARGO-UNCHANGED
2762
+
2763
+ A spike on 20 November 2026 for nxr-yfh7zh, on Linux x86-64 with 32 cores, cargo and rustc 1.91.0 and 1.100.0 through rustup's `+<toolchain>`, `nx` 24.0.6 and Node.js 26.12.0, in throwaway workspaces outside the repository. A _stage_ is a folder that cargo gets as `--target-dir <stage>`, with `--config 'build.build-dir="<build dir>"'` naming the build directory that cargo would use anyway. The cargo workspace had the binary crates `pa` and `pb`, which print `flag` where `RUSTFLAGS=--cfg flag` applies and `plain` otherwise. `pa` also has a build script that writes a file into `OUT_DIR` and prints `OUT_DIR` and `CARGO_TARGET_DIR`, an example, an integration test that runs `CARGO_BIN_EXE_pa`, and a library dependency `pd`. `pc` is a library with the crate types `cdylib`, `staticlib` and `rlib`. The fixtures `napi-addons` and `wasm-packages` were copied from `nx-rust/test/fixtures`. Unless a point names one version, both versions behaved the same.
2764
+
2765
+ - **Stable flags.** `--target-dir` with `--config build.build-dir=...` works on both stable versions. Cargo's `--artifact-dir` remains unstable on both. With the build directory of a plain `cargo build --workspace`, a staged `cargo build --workspace` compiled nothing and reported every crate `Fresh`.
2766
+ - **What lands in the stage.** The stage held `CACHEDIR.TAG` and, in the folder of the profile (`debug`, `release`) or of the triple and profile (`x86_64-unknown-linux-gnu/debug` with `--target`), the files that plain cargo puts in the artifact directory. These were the executables, `libpc.so`, `libpc.a`, the `rlib` files of the members, and their dependency records `pa.d`, `pb.d`, `libpc.d` and `libpd.d`, beside cargo's lock files and an empty `examples` folder. The executables and libraries were hard links of the build directory's files. Only the records and lock files took space of their own: 6 of 12 files on 1.91.0 and 6 of 13 on 1.100.0 had other links. The stage's `debug` folder held no `build` or `deps` folder. Cargo's `compiler-artifact` messages named the stage's files as `filenames` and `executable`, and the build directory's file only for a library's `rmeta`.
2767
+ - **Split debuginfo.** With `CARGO_PROFILE_DEV_SPLIT_DEBUGINFO=packed`, the stage also held `pa.dwp`, `pb.dwp` and `libpc.so.dwp`, and the messages listed each `.dwp` among the `filenames` of its target. `.dSYM` and `.pdb` were not tried.
2768
+ - **Build scripts.** The build script ran with `OUT_DIR` in the build directory: `target/debug/build/pa-<hash>/out` on 1.91.0, `target/debug/build/pa/<hash>/out` in 1.100.0's layout. `CARGO_TARGET_DIR` was unset for it. The build script's messages named the same `OUT_DIR`.
2769
+ - **Dependency records.** The stage's `pa.d` named its rule's target in the stage, and absolutely, or relative to `build.dep-info-basedir` where that is configured. On 1.100.0 it named the file that the build script generated in the build directory. On 1.91.0 it spelled that file under the stage, `<stage>/debug/build/pa-<hash>/out/gen.txt`, a path that does not exist, as 1.91.0 does with any build directory apart from the artifact directory ([[EVD-CARGO-DEP-INFO]]).
2770
+ - **The user's configuration.** `--target-dir` won over `CARGO_TARGET_DIR` and over `build.target-dir` in `.cargo/config.toml`; neither folder was created. `--config build.build-dir` won over `CARGO_BUILD_BUILD_DIR`, which created no folder, and every crate stayed `Fresh`. `cargo metadata --no-deps --format-version 1` reports both `target_directory` and `build_directory` on both versions. `build_directory` follows `CARGO_BUILD_BUILD_DIR` and equals `target_directory` where nothing sets it.
2771
+ - **Nothing else written.** No staged build touched a file of the artifact directory: inode and modification time of `target/debug/pa` stayed the same through a staged build of the same variant and of the other. With `--release`, no `target/release` was created. A stage inside the artifact directory, `target/.nx-rust-stage/<id>`, worked like one outside it. A plain `cargo build -p pb` with the flag did not touch `target/debug/pa` either, as [[EVD-CARGO-ARTIFACT-WRITERS]] found ("Feature sets of one crate").
2772
+ - **Plain cargo afterwards.** Plain cargo compiled the same crates in the sequence flag, plain, flag as in the same sequence with each build staged. On 1.91.0 that was 4, 1 and 1 crates; on 1.100.0, which keeps both variants, 4, 0 and 0. After a staged build of the other variant, plain `cargo build --workspace` linked `target/debug/pa` again, as it does after any build, and plain `cargo test --workspace` passed.
2773
+ - **Tests.** After a staged `cargo test --workspace --no-run` and the stage's removal, the test's record held `# env-dep:CARGO_BIN_EXE_pa=<stage>/debug/pa`. Plain `cargo test --workspace` then reported every crate `Fresh` and failed with status 101: cargo does not count the folder in the fingerprint of a test that names the executable. A stage is therefore no place for `cargo test` or `--all-targets`.
2774
+ - **Locks.** A second staged build with another stage, started while the first held the build directory through a build script that slept 4 s, waited 6.7 s on 1.100.0 ("Blocking waiting for file lock on build directory") and 7.1 s on 1.91.0 (first on the package cache). Two `nx` commands with stages of their own therefore take turns as plain cargo commands do.
2775
+ - **Interruption.** A staged build stopped by `SIGINT` during a build script left its stage with `CACHEDIR.TAG` and `debug`, and the artifact directory as it was. Plain cargo afterwards compiled nothing and reported every crate `Fresh`. Cargo leaves the stage to whoever made it.
2776
+ - **Cost.** A staged build that compiled nothing took 11 to 16 ms against 14 to 20 ms for plain cargo. No difference shows at that size.
2777
+ - **The stage's folder and plain cargo.** With a stage folder `target/.nx-rust-stage/<id>` left in the artifact directory, `cargo metadata --no-deps` reported the same directories, `cargo build --workspace` reported every crate `Fresh`, `cargo clean -p pa` left the folder's files alone and `cargo clean` removed it with the artifact directory.
2778
+ - **`--nx-bail`.** Read in Nx 24.0.6: `runTasks` of `tasks-runner/batch/run-batch.js` hands the batch implementation the batch's task graph, the combined options of each task, the last task's `overrides` and a context of `root`, `cwd`, `projectsConfigurations`, `nxJsonConfiguration`, `isVerbose: false`, `projectGraph` and `taskGraph`. `nxBail` stays among the orchestrator's `nxArgs` (`default-tasks-runner.js`, line 79), so a batch cannot tell that a run bails.
2779
+ - **`napi-build` and `wasm-build`.** The plugin runs their compile itself and hands the file that cargo reports to `@napi-rs/cli`'s functions or the `wasm-bindgen` CLI afterwards ([[DES-NAPI]], [[DES-WASM]]), so the flags reach cargo without going through either tool. In `napi-addons`, a staged `cargo build --workspace` with `NAPI_TYPE_DEF_TMP_FOLDER` set reported `libaddon_a.so`, `libaddon_b.so` and `libplain_cdylib.so` in the stage. The uplifted files of the artifact directory kept inode and modification time; on 1.91.0 only intermediates under `target/debug/deps` changed, as they do without a stage. In `wasm-packages` on 1.100.0, a staged `--target wasm32-unknown-unknown` build reported `codec.wasm`, `codec_b.wasm` and `plain_cdylib.wasm` in the stage's triple folder, and `wasm-bindgen` 0.2.130 turned the staged `codec.wasm` into `codec_bg.wasm`, `codec.js` and their type definitions. 1.91.0 has no wasm target installed here and was not tried for wasm.
2780
+
2781
+ **Through Nx.** The reviewer's probes of nxr-yfh7zh (the cached `pack`, the held `cargo build` of `pb`, the glob output, the early hash) were run with Nx 24.0.6 and cargo 1.100.0 against a throwaway prototype, never committed. It was the plugin compiled from commit d0971e5 with three changes: a `build` group that selects the whole workspace ran cargo with a stage under `.nx/workspace-data/nx-rust/stage/<pid>-<n>` and the build directory from `cargo metadata`; the files that the messages named for its own crates' `bin`, `cdylib` and `staticlib` targets, and the records beside them, were moved into the artifact directory and the stage removed; and the batch neither left groups for a following batch nor kept files.
2782
+
2783
+ | Probe | As on `main` and at d0971e5 | With the stage |
2784
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
2785
+ | `pack`, already running, reads `pa` while `pb`'s whole-workspace build is held | `flag`, and caches it | `plain`, and caches it |
2786
+ | A continuous task that depends on `pa:build` reads `pa` while `pb`'s build is held | `flag`, started between two waves | `plain`: with no group left out, one batch process ran both builds, and Nx started the continuous task after it, so the hold ran out (status 44) |
2787
+ | `pa:build` declares `{workspaceRoot}/rust/target/debug/p[a]`, and `pack` depends on it | `flag` at d0971e5 | `plain` |
2788
+ | `pb`'s build script runs `pa`, `pb` declares `dependentTasksOutputFiles: "**/pa"`, and the variable that `pa` prints is in `pa`'s key only; run with `old`, delete both executables, keep the cache, run with `new` | `pa` `new`, `pb` restored as `old` (nxr-f04xen) | `pa` `new`, `pb` built as `new` |
2789
+ | `--batch=false --parallel=1`, `pack` depending on both builds | `plain flag` | `plain` |
2790
+ | `pa:build-alt`, a copy of `pa:build` with `pa`'s `.env.build-alt` setting the flag and depending on `pa:build` | every entry `flag` | every entry `flag`: both own one path, which a stage cannot help |
2791
+
2792
+ In the cold run of both builds and `pack` with the stage, each restored executable matched what its own command built byte for byte, `pack` was restored as `plain`, and plain `cargo build --workspace -v` afterwards reported both crates `Fresh` without the flag and with it. The prototype's moved records let the build input check run unchanged. The runs used two or three small crates. macOS, `.dSYM`, other Nx versions, the `hakari` and `cargo` strategies through Nx, and wasm on 1.91.0 were not tried.
2793
+ :::
2794
+
2795
+ :::mara evidence EVD-CARGO-NESTED-DIRECTORY-CREATION
2796
+ :mid: 01M7FC5XF9QX97J7ZBYQVPPSN3
2797
+ :title: Two cargo commands that at once create artifact directories lying one inside the other
2798
+ :status: accepted
2799
+ :supports: DES-OUTPUTS
2800
+ :supports: DES-DIAGNOSTICS
2801
+
2802
+ Experiments on 15 November 2026 for nxr-cq1cx1, on Linux x86-64 with 32 cores and a btrfs file system, `nx` 24.0.6, Node.js 26.12.0, cargo 1.100.0 and 1.91.0, `RUSTUP_AUTO_INSTALL=0` and the Nx daemon off, on a machine whose load average was between about 7 and 50 from other work. Each run used a new copy of the fixture `shared-executables` laid out as its case "one workspace's artifact directory is the folder of a triple in another's" lays it out: `build.target-dir = "target"` in `.cargo/config.toml` at the repository root, `build.target-dir = "../target/x86_64-unknown-linux-gnu"` in `tools/.cargo/config.toml`, `beta`'s binary renamed, and `alpha`'s `build` for the host triple through its `project.json`. The artifact directory of `tools` is then the folder of that triple in the artifact directory of `rust` ([[DES-OUTPUTS]], "Files of one name"), and neither exists before the first build.
2803
+
2804
+ **Plain cargo.** `cargo build -p alpha --target x86_64-unknown-linux-gnu` in `rust/` and `cargo build -p tools` in `tools/`, started at once from a shell after `rm -rf target`, 100 rounds on each version. In 97 rounds on 1.100.0 and 99 on 1.91.0, one of the two printed `Blocking waiting for file lock on build directory`: both take the lock in `target/x86_64-unknown-linux-gnu/debug`, so they do not compile into the shared folder at once. In 2 of the 100 rounds on 1.100.0, and in none on 1.91.0, the command of `tools` failed before it took that lock, while that of `alpha` built:
2805
+
2806
+ ```text
2807
+ error: No such file or directory (os error 2) at path "<repository>/tools/../target/x86_64-unknown-linux-gnupP07y1"
2808
+ ```
2809
+
2810
+ A third series on 1.100.0, with `inotifywait -m -r` on the repository root and stopping at the first failure, failed in its 100th round in the same way, for `target/x86_64-unknown-linux-gnuvzrBTg`. Its first events below the root were `CREATE,ISDIR ./targetUe6sd6`, `CREATE,ISDIR ./target`, `MOVED_FROM,ISDIR ./targetUe6sd6` and `MOVED_TO,ISDIR ./target`; then `alpha`'s command created `target/debug` and `target/x86_64-unknown-linux-gnuxy4sVl`, renamed that to `target/x86_64-unknown-linux-gnu` and built there. No event shows the folder that the failed command named.
2811
+
2812
+ **A minimal pair.** Two packages made by `cargo new --vcs none`, `outer` and `inner`, with `build.target-dir = "../outer/target/inner"` in `inner/.cargo/config.toml`, built at once by plain `cargo build` after `rm -rf outer/target`: the command of `inner` failed with the same message, for `outer/target/inner` and a random suffix, in 3 of 300 rounds on 1.100.0 and in 4 of 500 on 1.91.0, while that of `outer` built. Here the two commands take no common build lock, and none is needed for the failure. A traced failing round showed the same events: `CREATE,ISDIR outer/targetcKA3Xn`, `CREATE,ISDIR outer/target`, `MOVED_FROM,ISDIR outer/targetcKA3Xn` and `MOVED_TO,ISDIR outer/target`. Cargo's `create_dir_all_excluded_from_backups_atomic` (`cargo-util`, `paths.rs`, read on doc.rust-lang.org) documents that it creates missing parent folders without that atomicity: it creates the parent with `create_dir_all`, the folder with the random suffix in it with `tempdir_in`, marks that folder excluded from backups, which writes `CACHEDIR.TAG`, and renames it onto the path, taking a failed rename as success where the path then exists.
2813
+
2814
+ **What fails.** Cargo creates an artifact directory that does not exist yet as a folder with a random suffix beside it, which it renames into place, as the events show; the rounds in which both commands built show that it accepts a directory that the other command created meanwhile. The parent of the folder with the suffix it creates first, as a plain folder. So `tools`' command created `target` as the parent of `target/x86_64-unknown-linux-gnu`, and `rust`'s command, whose artifact directory is `target`, renamed its own folder onto it. A rename onto an empty folder replaces it, and creating an entry in the replaced folder fails with ENOENT. Two Python processes that a barrier started together showed this on the same machine: one created `target` and then a folder in it, the other renamed a folder that holds a file onto `target`, and in 13 of 3,000 rounds the first one's second step failed with ENOENT. A folder that cargo renames into place holds `CACHEDIR.TAG`, so it is never empty and no rename replaces it: on both versions, `tools`' command alone left `target` holding only the triple's folder and `target/x86_64-unknown-linux-gnu` holding `CACHEDIR.TAG`, while `rust`'s command alone, which renames both into place, left `CACHEDIR.TAG` in both. Only the parent that the inner command creates as a plain folder can be replaced. Two workspaces with the same artifact directory therefore do not meet this, and neither do runs that find both directories.
2815
+
2816
+ **Through Nx.** The first `nx run-many -t build` in such a copy starts `rust:lockfile`, `alpha:build` and `tools:build` together, Nx's default of three tasks at once, since neither uncached `build` depends on the lockfile task. 7 of 750 such runs failed on 1.100.0 and 7 of 500 on 1.91.0, each time `tools:build` with the message above, while `alpha:build`, `gamma:build` and `beta:build` built. With `--parallel=1`, which runs one task at a time, none of 500 failed on 1.100.0. The test case as a whole, whose later commands find both directories, passed 384 of 384 runs on 1.100.0 before its first command had `--parallel=1`, at load averages of about 19 and, with 32 busy loops beside it, about 50, and 50 of 50 with it.
2817
+
2818
+ So two cargo commands that at once create artifact directories lying one inside the other can fail in cargo itself, before either takes its build lock, wherever the outer directory does not exist yet: on a first build, in a fresh checkout, or after `cargo clean`. A second run, which finds the directories, builds. Plain cargo fails in the same way when two such commands start at once. `cargo check`, `cargo test --no-run` and `cargo doc` in `tools/` alone created its artifact directory in the same way on 1.100.0, with `CACHEDIR.TAG` in it, so other commands than `build` can meet this as well; that they do was not tried, nor macOS, other file systems, or a build directory (`build.build-dir`) inside another workspace's artifact directory.
2819
+ :::
2820
+
2821
+ :::mara evidence EVD-CARGO-PACKAGE-SPECS
2822
+ :mid: 01M7DDYY0FZTWB37H3FWXCG5AF
2823
+ :title: A package ID specification selects a member that another package of the resolve shares a name with
2824
+ :status: accepted
2825
+ :supports: DES-INVOCATION
2826
+ :supports: DES-TARGET-COMMANDS
2827
+
2828
+ Experiments on 14 November 2026 on Linux x86-64 with cargo 1.100.0 and 1.91.0, the older through a private `RUSTUP_HOME` with `RUSTUP_AUTO_INSTALL=0`, in throwaway workspaces outside this repository; then with the plugin built from this repository, in a copy of the fixture `shared-names`. A workspace had the members `good` 0.1.0 in `crates/good`, `app` with a binary, and `renamed` in `crates/folder-x`. In one copy `good` depended on `old = { package = "good", path = "../../../outside/good" }`, a package `good` 0.2.0 outside the workspace; in another it depended on `published = { package = "good", version = "0.1.0" }` from a directory registry that `[source.crates-io]` in the workspace's `.cargo/config.toml` put in place of crates.io, so that the resolve held a registry package with the member's name and version.
2829
+
2830
+ - **When a name is ambiguous.** `-p good` is matched against the packages that the selection reaches, not against the members. Where only `app` depended on the other `good`, `cargo test -p good`, `cargo test --doc -p good` and `cargo check -p good` worked, and `cargo test --doc -p good -p app` failed with "specification `good` is ambiguous". Where `good` itself depended on it, every command with `-p good` failed, on both versions; cargo 1.91.0 said "There are multiple `good` packages in your project, and the specification `good` is ambiguous." With the path package, the message offered `good@0.1.0` and `good@0.2.0`; with the registry package, `-p good@0.1.0` failed too, and the message offered `path+file:///<workspace>/crates/good#0.1.0` and `registry+https://github.com/rust-lang/crates.io-index#good@0.1.0`.
2831
+ - **The fully qualified form.** `cargo pkgid --manifest-path crates/good/Cargo.toml` printed `path+file:///<workspace>/crates/good#0.1.0`, and for `renamed`, whose folder has another name, `path+file:///<workspace>/crates/folder-x#renamed@0.1.0`, the name before the version. The `id` of each member in `cargo metadata --format-version 1 --no-deps` was the same string, on both versions. `cargo pkgid` failed with "a Cargo.lock must exist for this command" where the workspace had no lockfile; `cargo metadata --no-deps` reported the ids and created none. In a workspace with 300 members it took about 12 ms.
2832
+ - **What accepts it.** With that form, `cargo test`, `cargo test --doc`, `cargo test --no-fail-fast` with three of them, `check --all-targets`, `clippy --all-targets`, `build`, `build --locked`, `doc --no-deps`, `bench`, `run`, `update --dry-run` and `--workspace --exclude`, once and twice, succeeded with both dependencies and both versions. `cargo fmt -p` and `cargo fmt --check -p` rejected it with "package `path+file:///…#0.1.0` is not a member of the workspace". `cargo fmt -p good` matched the member only: it formatted `crates/good` and left the `good` outside the workspace as it was.
2833
+ - **What cargo prints.** With `good`'s unit test and doctest failing, `cargo test --no-fail-fast` with the specifications of `good` and `app` printed "to rerun pass `-p good --lib`" and "`-p good --doc`", and the closing list named `` `-p good --lib` `` and `` `-p good --doc` ``, on both versions: the bare name, which the user cannot paste in this workspace.
2834
+ - **Paths.** In a folder named `sp ace`, the space was `%20` in both the `id` and `cargo pkgid`, and `cargo test -p` with it worked. Through a symbolic link `link-wsp` to the workspace, `cargo metadata --manifest-path link-wsp/Cargo.toml` reported `path+file:///<parent>/link-wsp/crates/good#0.1.0`, while cargo started in the link, from a shell or from Node with the link as its folder, reported the real path, as the operating system gives cargo its folder. `cargo check -p` with the specification through the link failed in the real folder with "package ID specification `…` did not match any packages", and worked with `--manifest-path` through the link.
2835
+ - **Through the plugin.** Built from this repository before the change, the plugin ran `build`, `check`, `lint`, `test`, `bench` and `run` of `good` with `-p good`, and each failed with "specification `good` is ambiguous"; in the registry copy, `kit` in `crates/toolkit` with a registry `kit` 0.1.0, every target with `-p kit` failed in the same way. `fmt-check` and the lockfile task passed in both. With each task asking cargo for the member's `id` in the workspace root, every target of both crates passed with cargo 1.100.0, and with `RUSTUP_TOOLCHAIN` set to 1.91.0.
2836
+
2837
+ So a name, and a name with its version, can be ambiguous wherever the packages that a command reaches include another package of that name, which the `--no-deps` report does not show. The specification that cargo reports for the member is unambiguous for every command but `cargo fmt`, which takes names and matches only members. It holds the path through which cargo reached the workspace, so it has to be asked where the command starts.
2838
+ :::
2839
+
2840
+ :::mara evidence EVD-WORKSPACE-TEST-SELECTION
2841
+ :mid: 01M7DMTE8WX7EFV63DCFSGAWWJ
2842
+ :title: How a test step runs only some crates' tests while it compiles the whole workspace
2843
+ :status: accepted
2844
+ :supports: ADR-TEST-SELECTING-RUNNER
2845
+ :supports: DES-TEST-RUN
2846
+ :supports: DES-UNIFICATION
2847
+ :supports: RISK-TEST-RUNNER-MACOS
2848
+
2849
+ Superseded in part: since the maintainer's decision of 14 November 2026 ([[ADR-TEST-SELECTING-RUNNER]]), doctests no longer go through a runner, so what this item finds about doctests started through the runner records why that design was given up; [[EVD-TEST-STEPS-SPLIT]] holds the experiments of the design that replaced it. Its findings on selection, features, fingerprints, a runner that the user configured, the cost of the runner's start and nextest still hold.
2850
+
2851
+ Experiments on 14 November 2026 on Linux x86-64 with cargo 1.100.0 (3acc79c0c 2026-11-05) and 1.91.0 (ea2d97820 2025-10-10), Node 26.12.0 and cargo-nextest 0.9.152 (26ebeda79 2026-11-13), the released binary in a folder of its own, with `RUSTUP_AUTO_INSTALL=0`, a Cargo home of their own, offline, in throwaway folders outside this repository. Two sets of runs are recorded: those of the research for [[ADR-TEST-SELECTING-RUNNER]], whose commands and outputs are taken as its report gives them (marked _research_), and those run for this item, which repeated the central cases on both versions and added the rest (marked _rerun_). The rerun's workspace had resolver 2 and these members: `shared`, with a feature `x`; `a`, which depends on `shared` without features and on a path crate `ext` outside the workspace with its feature `e1`; `b`, which depends on `shared` with `x` and on `ext` with `e2`; `ab`, with 300 doctests in edition 2021; `c`, in edition 2024 with 201 doctests, whose unit test, integration test and one doctest fail when `C_FAIL` is set and which has a test that sleeps for 2 s; and `binonly`, with only `src/main.rs`. The research's workspace was alike, with 200 and 202 doctests. The selecting runner was a Node script, started as `["/usr/bin/node", "<script>"]`, that took the group as a JSON list, ran the programs of its packages, recorded skips and failed closed; the runner that [[DES-TEST-RUN]] now describes, which records every start and its end, is tried in [[EVD-TEST-RUNNER-EVIDENCE]]; a `/bin/sh` script with the same logic, started as `["<script>"]`, served for the timings.
2852
+
2853
+ - **Selecting crates narrows the features** (rerun; research for `--exclude` and the target flags). After `cargo test --no-run --workspace`, `cargo test --doc -p a` compiled `ext`, `shared` and `a` again, on both versions. `--workspace --exclude` narrowed the features as `-p` did, `--lib` ran the unit tests of every library, and unit-test names such as `tests::it_works` carry no crate (research). With `resolver.feature-unification = "workspace"` given by `--config`, or `CARGO_RESOLVER_FEATURE_UNIFICATION=workspace`, both versions printed "warning: ignoring `resolver.feature-unification` without `-Zfeature-unification`", and `cargo test --no-run -p b` compiled `ext` and `b` again; with `-Zfeature-unification` added, both failed with "the `-Z` flag is only accepted on the nightly channel of Cargo, but this is the `stable` channel" and exit code 101. The research found the same with the setting in `.cargo/config.toml`.
2854
+ - **The runner runs only the selected crates** (rerun; research with a shell script). `C_FAIL=1 NX_RUST_TEST_PACKAGES='["a","b"]' cargo test --workspace --no-fail-fast --config 'target.x86_64-unknown-linux-gnu.runner=["/usr/bin/node","<script>"]'` exited with 0 and compiled nothing, on both versions. The unit test, integration test and doctest of `a` and of `b` passed, and no test of `c` ran, its failing tests and its 2-second test included. Cargo started the runner for each test binary and rustdoc for each doctest, the same on both versions: for `a` 3 times (2 binaries, 1 doctest), `b` 3, `ab` 301, `binonly` 1, `c` 3 (2 binaries and one merged program for its 201 doctests) and `shared` 2, each time in the package's folder and with the package's name in `CARGO_PKG_NAME`, also for doctests that rustdoc ran from its temporary folder. In a second workspace, a package `other` whose library is named `good`, beside a package `good`, and a package `my-crate` in edition 2024 had their own names in `CARGO_PKG_NAME`, while cargo printed `Doc-tests good` for both `good` and `other`, and `Doc-tests my_crate`. The `Running` line of each test binary named the path that the runner received as its program. With `c` selected and `C_FAIL=1`, its 2-second test ran, and cargo ended with "3 targets failed:" `` `-p c --lib` ``, `` `-p c --test c_it` `` and `` `-p c --doc` `` and exit code 101.
2855
+ - **A skip looks like a pass** (rerun; the control plane's check found it first). For each skipped doctest of `ab`, rustdoc printed a line such as `test crates/ab/src/lib.rs - f1 (line 1) ... ok`, and then `test result: ok. 300 passed`, on both versions. A skipped test binary left only cargo's `Running` line. The skipped merged program of `c` printed no test line: cargo 1.100.0 printed only "all doctests ran in 0.23s; merged doctests compilation took 0.22s", cargo 1.91.0 nothing. A skipped standalone `should_panic` doctest, which this workspace lacked, is reported as failed ([[EVD-TEST-RUNNER-EVIDENCE]]).
2856
+ - **Failing closed** (rerun). With `NX_RUST_TEST_PACKAGES='a b'`, which is no JSON list, the runner exited with 125 at every call and cargo listed all 14 targets of the workspace as failed; without the variable, the doctest step failed with exit code 101. Without `CARGO_PKG_NAME`, and with it empty, the runner exited with 125 and started nothing. With the record folder missing, each skip failed, and cargo listed every target of the crates outside the selection as failed while those of `a` passed. The integration test of `a` asserted that neither of the runner's two variables reached it, and passed through the runner. That workspace had no `should_panic` doctest; for such a doctest rustdoc counts the runner's failure as a pass ([[EVD-TEST-RUNNER-EVIDENCE]]).
2857
+ - **Nothing is compiled again** (rerun; research for its shell script). After `cargo test --no-run --workspace`, runs with the runner and the selections `a b`, `c`, `shared binonly` and `a`, `cargo build --workspace`, `cargo test --no-run --workspace`, the doctest step with the runner and `cargo test --workspace` without it compiled nothing, on both versions: neither the runner nor its variables enter a fingerprint.
2858
+ - **A compile error stops the step** (rerun). With a unit test of `c` that does not compile, the run with the selection `a b` exited with 101 after "error: could not compile `c` (lib test) due to 1 previous error" and printed no `test result` line, on both versions. With the library of `c` broken, the doctest step stopped after "could not compile `c` (lib)".
2859
+ - **The library path** (rerun; research for macOS, read and not run). A test of a member `user`, linked against a member `dy` of crate type `dylib` and built with `RUSTFLAGS="-C prefer-dynamic"`, passed through the Node runner on both versions; run directly, it failed with "error while loading shared libraries: libdy.so: cannot open shared object file". On macOS cargo sets `DYLD_FALLBACK_LIBRARY_PATH` instead of `LD_LIBRARY_PATH`, and the system removes `DYLD_*` variables when it starts a binary that System Integrity Protection protects, such as `/bin/sh` and `/usr/bin/env`.
2860
+ - **Start-up of the runner** (rerun, cargo 1.100.0, 32 cores). 200 starts one after another, each running `/bin/true` for a selected package, took 4.0 s through the Node script, 0.17 s through the shell script and 0.06 s without a runner; 200 skips took 3.6 s and 0.18 s. Steady-state steps, three rounds each, the 304 starts of the doctest step being 300 for `ab`, one each for `a`, `b` and `shared`, and one for the merged program of `c`:
2861
+
2862
+ | Step | No runner | Shell script | Node script |
2863
+ | -------------------------------------------------------- | ----------- | ------------ | ----------- |
2864
+ | `cargo test --doc --workspace`, every crate selected | 2.15–2.26 s | 1.85–2.07 s | 2.61–2.65 s |
2865
+ | the same with `-- --test-threads=4` | 4.50–4.67 s | 3.67–4.16 s | 5.50–5.62 s |
2866
+ | the same with 4 threads and the selection `a b` | | 3.86–4.08 s | 5.11–5.48 s |
2867
+ | `cargo test --workspace` with the selection `a b` | | 1.89–2.12 s | 2.62–2.80 s |
2868
+ | `cargo test --workspace`, every crate selected, 2 s test | | 3.94–4.03 s | 4.74–4.90 s |
2869
+
2870
+ The research measured 0.09 s for `cargo test -p a -p b` and 3.3 s for `cargo test --workspace` in its workspace.
2871
+
2872
+ - **A runner that the user configured** (rerun). A logging runner was configured in `.cargo/config.toml` of the workspace and `cargo test` run with and without `--config 'target.x86_64-unknown-linux-gnu.runner=[…]'` naming the selecting runner:
2873
+
2874
+ | User's runner | Plain `cargo test`, both versions | With the selecting runner, 1.100.0 | With the selecting runner, 1.91.0 |
2875
+ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
2876
+ | `runner = ["<user>"]` under `[target.x86_64-unknown-linux-gnu]` | the user's | the selecting runner only | the user's, with the selecting runner and the program as its arguments |
2877
+ | `runner = "<user>"`, a string, there | the user's | cargo fails: "failed to merge key `runner` between … and --config cli option" | the same failure |
2878
+ | under `[target.'cfg(unix)']` | the user's | the selecting runner only | the selecting runner only |
2879
+ | two tables, `cfg(unix)` and `cfg(target_os = "linux")` | cargo fails: "several matching instances of `target.'cfg(..)'.runner` in configurations" | the selecting runner only, no error | the selecting runner only, no error |
2880
+ | `CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER`, in place of the file | the user's, also over a runner in the file | the selecting runner only | the user's only |
2881
+
2882
+ Under `[target.'cfg(nxr_flag)']`, plain cargo ran no runner, and the user's with `RUSTFLAGS="--cfg nxr_flag"` or with `build.rustflags` naming that flag, on both versions. Only in a file that `include = ["extra.toml"]` adds, the runner applied on 1.100.0 and not on 1.91.0; `include = "extra.toml"` made 1.100.0 fail with "expected a list of strings or a list of tables, but found string at `include`", while 1.91.0 ignored it; an `[[include]]` table with `optional = true` and a missing file passed on 1.100.0 and failed on 1.91.0 with "could not load Cargo configuration". A runner in the Cargo home's `config.toml`, and one named by a relative path in `.cargo/config.toml`, applied on both. Of two runners given with `--config`, the later applied, on both. `cargo config get` failed on both: "the `cargo config` command is unstable, and only available on the nightly channel of Cargo".
2883
+
2884
+ - **nextest** (research; the cases with a result rerun with 0.9.152 on both versions). After `cargo test --no-run --workspace`, `C_FAIL=1 cargo nextest run --workspace --no-fail-fast --no-tests=pass -E 'package(=a) | package(=b)'` exited with 0 and compiled nothing, printing "Starting 4 tests across 4 binaries (5 binaries skipped)"; the research's logging runner showed that nextest started the binaries of `a` and `b` only. A filterset that matched no test, `package(=a) & test(=nosuch)`, failed with exit code 4 and "error: no tests to run", and passed with `--no-tests=pass`; the research found the same with `package(shared)`. `package(=x)` for a name that no package has failed with exit code 94, "operator didn't match any packages". `package(a*)` matched `a` and `ab`, `package(=a)` only `a`. With a unit test of `c` that does not compile, the run stopped before any test with "command `…/cargo '--color=never' test --no-run '--message-format=json-render-diagnostics' --workspace` exited with code 101" (research, both versions): nextest builds through `cargo test --no-run` and stops as `cargo test` does. The doctest step with the selecting runner after it compiled nothing and skipped 302 programs (rerun).
2885
+
2886
+ So stable cargo has no flag that leaves out crates without narrowing features, while a runner given with `--config` and a nextest filterset keep the whole-workspace build on both versions and run the selected crates' tests only. Cargo and rustdoc count a skip as a pass, so a result must not rest on it, and rustdoc counts a runner's failure as a pass for a `should_panic` doctest ([[EVD-TEST-RUNNER-EVIDENCE]]). A runner given on the command line replaces the user's on 1.100.0, and on 1.91.0 is appended to it, fails beside it or loses to it, and stable cargo cannot say which runner applies. Not run: macOS, dash or another `/bin/sh` than bash, large workspaces, and cargo-affected under `--workspace` ([[RISK-CARGO-AFFECTED]]).
2887
+ :::
2888
+
2889
+ :::mara evidence EVD-TEST-RUNNER-EVIDENCE
2890
+ :mid: 01M7DQV5AEH9FVXN5XCW749Y6G
2891
+ :title: What shows that a program started through a runner ran
2892
+ :status: accepted
2893
+ :supports: ADR-TEST-SELECTING-RUNNER
2894
+ :supports: DES-TEST-RUN
2895
+ :supports: DES-BATCH
2896
+ :supports: DES-UNIFICATION
2897
+ :supports: RISK-TEST-RUNNER-MACOS
2898
+
2899
+ Superseded in part: the record, the check and the counts tried here were for doctests run through a runner, which the plugin no longer does ([[ADR-TEST-SELECTING-RUNNER]]); the item stays as the record of why. Its findings that a group of one task needs whole-workspace selection, and how cargo lists a failure in a workspace with one member, still hold.
2900
+
2901
+ Experiments on 14 November 2026 on Linux x86-64 with cargo 1.100.0 and 1.91.0, Node 26.12.0 and bash 5.3.20 as `/bin/sh`, with `RUSTUP_AUTO_INSTALL=0`, a Cargo home of their own, offline, in throwaway folders outside this repository, run after a review of the selecting runner that reported the first three wrong passes below. Every result held on both versions unless it says otherwise. Each doctest wrote a marker file before anything else, so that a marker shows that its code ran.
2902
+
2903
+ - **What the runner learns.** A probing runner logged, for each start, `CARGO_PKG_NAME`, the program and the environment. No `UNSTABLE_RUSTDOC_TEST_PATH`, `UNSTABLE_RUSTDOC_TEST_LINE` or other variable of rustdoc reached it, so it cannot tell which doctest it starts. Each standalone doctest that ran was one start of rustdoc's `rust_out` in a folder of its own; a crate in edition 2024 had one start for its merged program, whose folder also held `doctest_runner_2024.rs`, `doctest_bundle_2024.rs` and `libdoctest_bundle_2024.rlib`. Doctests marked `no_run`, `compile_fail` and `ignore` started nothing. A standalone `should_panic` doctest that panicked ended with 101, one that called `std::process::exit(3)` with 3. rustdoc's line for a standalone `should_panic` doctest carried no mark, `test a/src/lib.rs - p (line 5) ... ok`, while those of merged doctests did, `... - should panic ... ok`; `no_run` and `compile_fail` doctests are marked ` - compile` and ` - compile fail`.
2904
+ - **Wrong passes of the first runner.** The members `a1` and `a2`, in edition 2021 with `[lib] test = false`, each had one `should_panic` doctest that writes its marker and then panics, and `m1`, in edition 2024, the same. With the runner of [[EVD-WORKSPACE-TEST-SELECTION]] and `NX_RUST_TEST_PACKAGES=bad`, the runner exited with 125 at every start, and rustdoc printed `test a1/src/lib.rs - f (line 1) ... ok` and the same for `a2`, with no marker and no record. A valid list with `NODE_OPTIONS=--not-a-real-node-option`, under which the runner never started, gave the same. Only `m1` failed, because rustdoc counts a non-zero exit of a merged program as a failure. In a workspace with a member `dy` of crate type `dylib`, built with `RUSTFLAGS="-C prefer-dynamic"` and with the toolchain's `lib/rustlib/<host>/lib` on `LD_LIBRARY_PATH`, plain cargo passed the doctests of `dl` (edition 2021), `dm` (2024) and `dp` (one `should_panic` doctest) and wrote every marker. With `LD_LIBRARY_PATH` removed in the runner's process by `/usr/bin/env -u LD_LIBRARY_PATH` before the runner, the loader failed with status 127, and the `should_panic` doctests of `dp` and `dl` were reported `ok` with no marker. Plain cargo does the same on its own: with `RUSTDOCFLAGS="-C prefer-dynamic"`, under which the doctest could not find `libstd`, it reported the `should_panic` doctest `ok`.
2905
+ - **Merged doctests with a runner.** With any runner, the merged program printed "WARNING: No rustdoc doctest environment variable provided so doctests will be run in the same process". Its doctest that called `std::process::exit(3)` ended the program with status 3, cut off the lines of the doctests after it and failed the crate, where plain cargo ran each merged doctest in a process of its own and passed them all. With a doctest that called `std::process::exit(0)` before one that fails, cargo exited with 0 and printed no test line, where plain cargo reported `b1 ... FAILED` and exited with 101. A runner that set `RUSTDOC_DOCTEST_BIN_PATH` to the merged program's path gave the same lines and status as plain cargo in both cases, without the warning. Plain rustdoc does not give a standalone doctest that variable: one that read it found none.
2906
+ - **The record and the check.** Prototypes of the two runners of [[DES-TEST-RUN]], a `/bin/sh` script and a Node script, recorded each start before anything else and then its end, and a script applied the plugin's three conditions to the record and to cargo's two output streams, read as one. With a valid list every task passed and every marker was written. With `bad`, every start had an error entry and `a1`, `a2` and `m1` failed. The Node runner under the bad `NODE_OPTIONS` left no record, and `a1` and `a2` failed on the count, one doctest reported and none recorded, and `m1` on cargo's list; the shell runner under the same variable passed. With `LD_LIBRARY_PATH` removed in either runner's process, every start ended with 127, and `dl`, `dm` and `dp` failed, `dp` on the record alone. With the record folder missing or read-only, nothing was recorded, and `a1` and `a2` failed on the count. With the runner killed after it recorded its start, and with an end that could not be recorded, the records had no end, and every task failed, also where the markers show that the doctests ran. A standalone `should_panic` doctest that calls `std::process::exit(3)` failed its crate on the status 3, where plain cargo passes it; the same doctest in a merged program passed, as under plain cargo. With one crate selected, another crate's skipped standalone `should_panic` doctest exited with 0 and rustdoc reported it as failed, so cargo exited with 101 while the selected task passed. 300 standalone doctests, a merged program of 200 doctests and three test binaries in one step gave 304 records, each with its start and the status 0, and the check passed.
2907
+ - **`panic = "abort"`.** In `[profile.dev]` and `[profile.test]` it was ignored for tests, with cargo's warning, and a panicking doctest still ended with 101. With `RUSTDOCFLAGS="-C panic=abort"` it ended with status 134, SIGABRT as the shell reports it, which plain rustdoc counts as a pass for a `should_panic` doctest.
2908
+ - **Cargo's list without `-p`.** Under `--workspace` in a workspace with one member, cargo printed "to rerun pass `--doc`" and listed `` `--doc` ``; with `-p e`, and with two members or a root package beside the member, it named the package.
2909
+ - **The shell.** `/bin/sh` did not read a script named by `ENV` or `BASH_ENV`. With `SHELLOPTS=errexit`, bash as `/bin/sh` ended the runner right after a failing program, before it recorded the end; with the options reset as the script's first command, the end was recorded. Under `noexec` and `onecmd` the reset cannot help ([[EVD-TEST-RUNNER-SILENT-EXIT]]).
2910
+ - **Cost** (cargo 1.100.0, 32 cores, three rounds each). 200 starts one after another, each of `/bin/true` for a selected package, took 0.19 s through the recording shell script, 3.0 s through the recording Node script and 0.04 s without a runner. A test step with 304 starts took 1.67–1.74 s without a runner, 1.67–1.86 s through the shell script and 2.03–2.23 s through the Node script with 32 test threads, and 2.67–2.76 s, 2.86–3.02 s and 4.15–4.39 s with `--test-threads=4`.
2911
+ - **A group of one task.** A member `a` depends on `shared` without its feature `x`, a member `b` switches `x` on, and a test of `a` asserts that `x` is off: `cargo test -p a` passed, and `cargo test --workspace` with the runner selecting `a` failed that test.
2912
+
2913
+ So the status that cargo or rustdoc reports does not show that a program ran, while a record of every start and its end, with the count of standalone doctests, caught each case tried; a runner that ends with 0 before it records anything was not among them, and [[EVD-TEST-RUNNER-SILENT-EXIT]] shows that every kind of program then needs comparing. A runner takes away the isolation of merged doctests unless the variable is set, and selecting one crate with `-p` under `workspace-build` gives it other features than the whole workspace. Not run: macOS, and a `/bin/sh` other than bash.
2914
+ :::
2915
+
2916
+ :::mara evidence EVD-TEST-RUNNER-SILENT-EXIT
2917
+ :mid: 01M7DT543KQM8ZV17Y8RQK1SAZ
2918
+ :title: What cargo shows of each program that a runner starts, and how a runner can end with 0 without running
2919
+ :status: accepted
2920
+ :supports: DES-TEST-RUN
2921
+ :supports: ADR-TEST-SELECTING-RUNNER
2922
+ :supports: RISK-TEST-RUNNER-MACOS
2923
+
2924
+ Superseded in part: the comparison of the record with cargo's and rustdoc's human-readable output tried here was given up ([[ADR-TEST-SELECTING-RUNNER]]), and test binaries are now compared with cargo's JSON messages ([[EVD-TEST-STEPS-SPLIT]]). That a runner's interpreter can end with 0 before it records anything still holds.
2925
+
2926
+ Experiments on 14 November 2026 on Linux x86-64 with cargo 1.100.0 and 1.91.0, the merged line also with 1.97.1, 1.98.1 and 1.99.0, Node 26.12.0 and bash 5.3.20 as `/bin/sh`, with `RUSTUP_AUTO_INSTALL=0`, a Cargo home of their own, offline, in throwaway folders outside this repository, after a second review of the selecting runner reported the first case. The prototypes of [[EVD-TEST-RUNNER-EVIDENCE]] served as runners, and a script applied the plugin's conditions. Every result held on both versions unless it says otherwise. The workspace had the members `u`, edition 2021, with a failing unit test and a passing integration test; `m`, edition 2024 with `[lib] test = false`, with one failing doctest, merged; `s`, edition 2021, with one passing doctest; and `e`, with a unit test that writes the `SHELLOPTS` and `BASHOPTS` it sees. Each test wrote a marker before anything else.
2927
+
2928
+ - **A runner that ends with 0 without running.** `env SHELLOPTS=noexec /bin/sh -c 'set +n; printf RAN'` printed nothing and exited with 0. Under `SHELLOPTS=noexec`, and under `SHELLOPTS=onecmd`, with which bash ran the script's first line only, `cargo test --workspace --no-fail-fast` with the shell runner exited with 0, wrote no record and no marker, and a check of the three conditions of the second round passed `u` and `m`, whose tests fail; only `s` failed, on its count. Plain cargo in the same environment ran every test and exited with 101. `NODE_OPTIONS=--require=<preload>`, with a preload that calls `process.exit(0)` for the runner's script, and `NODE_OPTIONS='--import=data:text/javascript,process.exit(0)'` did the same to the Node runner. An exported function `BASH_FUNC_printf%%='() { :; }'` left record files without content while the tests ran. `NODE_OPTIONS=--check` was refused with exit code 9, and `BASHOPTS=failglob` changed nothing.
2929
+ - **What cargo prints for each program.** Cargo printed `Running unittests src/lib.rs (<path>)` and `Running tests/it.rs (<path>)` before each test binary that it started through the runner, also where the runner did nothing; the path counted from the workspace root, and with `CARGO_TARGET_DIR` outside the workspace it was absolute. Compared by real path, the printed paths were the paths that the runner received, two of two in both layouts on both versions. For standalone doctests rustdoc printed one line each, also where the runner did nothing. For a merged program that did nothing, cargo 1.100.0, 1.99.0, 1.98.1 and 1.97.1 printed rustdoc's line `all doctests ran in …; merged doctests compilation took …` in the crate's block. Cargo 1.91.0 printed it for a crate with merged and standalone doctests, but for a crate whose doctests are all merged printed the `Doc-tests m` header and nothing else, where a crate without doctests gives `running 0 tests` on every version tried and a crate with only standalone doctests gives no merged line.
2930
+ - **The check with every kind compared.** With a record required for every `Running` line and for every block with the merged line or without any run of libtest, `u`, `m`, `s` and `e` all failed under `noexec`, `onecmd`, the exported `printf` and the Node preload, with no marker written in the first three; In the workspace of [[EVD-TEST-RUNNER-EVIDENCE]] whose members have doctests only, `m1` failed under `noexec` on its merged program alone, also as the only selected crate, on 1.91.0 through its empty block and on 1.100.0 through the merged line. Valid runs passed `s` and `e` and failed `u` and `m` through cargo's list, as plain cargo does; the cases of [[EVD-TEST-RUNNER-EVIDENCE]], run again, gave the same results as there.
2931
+ - **Starting the shell without the options.** With the runner started as `/usr/bin/env -u SHELLOPTS -u BASHOPTS /bin/sh <script>` and the user's values handed to the program through `/usr/bin/env`, `SHELLOPTS=noexec`, `onecmd` and `errexit` with `BASHOPTS=nullglob` gave complete records and the results of a valid run, and the test of `e` saw `SHELLOPTS` and `BASHOPTS` exactly as under plain cargo. With the runner started as `/bin/sh <script>` and `SHELLOPTS=errexit`, the reset in the script ran, and the test saw a `SHELLOPTS` without `errexit`.
2932
+
2933
+ So a runner's interpreter can end with 0 before the script does anything, in ways that no reset inside the script can stop, and only a comparison of every program that cargo's output reports with the record catches it. Cargo's output reported every program in the shapes tried, the merged programs through rustdoc's merged line or an empty block. Not run: macOS, Cargo 1.92 to 1.96, and a `/bin/sh` other than bash.
2934
+ :::
2935
+
2936
+ :::mara evidence EVD-NX-24-VERBOSE
2937
+ :mid: 01M7DPAR4595KRB69GS95QAF1V
2938
+ :title: How Nx 24.0.6 tells a task that it runs verbosely, and what it stores of what the task prints
2939
+ :status: accepted
2940
+ :supports: DES-INVOCATION
2941
+ :supports: ADR-VERBOSE-COMMAND
2942
+
2943
+ A reading of the `nx` 24.0.6 package that this repository installs (paths under `dist/`), and runs on 14 November 2026 through this repository's test harness with Node.js 26.12.0 and cargo 1.100.0 on Linux, in copies of the fixture `shared-names`, with the plugin compiled from this repository and its executor printing the command in verbose mode (`nx-rust/test/verbose-command.spec.ts`).
2944
+
2945
+ - **The flag and the variable.** `nx run`, `nx run-many` and `nx affected` take `--verbose` through `withVerbose` in `src/command-line/yargs-utils/shared-options.js`. Its middleware takes `NX_VERBOSE_LOGGING === 'true'` where the flag is missing, and then sets `process.env.NX_VERBOSE_LOGGING` of the `nx` process to `true` or `false`; `src/command-line/run-many/run-many.js` sets it to `true` again for `--verbose`. The flag thus wins over the variable both ways. Through the harness, `nx run` printed a task's command with `--verbose`, with `NX_VERBOSE_LOGGING=true` and with `--verbose` beside `NX_VERBOSE_LOGGING=false`, and printed none without either and with `--verbose=false` beside `NX_VERBOSE_LOGGING=true`, with the Nx daemon off and on; `nx run-many --verbose` printed it as well.
2946
+ - **What a task's executor gets.** Nx runs the executor of every task but `nx:run-commands` in a process of its own (`runTask` in `src/tasks-runner/task-orchestrator.js`). `ForkedProcessTaskRunner` reads `process.env.NX_VERBOSE_LOGGING === 'true'` when it is created and sends it with each task as `isVerbose` (`src/tasks-runner/forked-process-task-runner.js`). `bin/run-executor.js` hands that to `runExecutorInternal` in `src/command-line/run/run.js`, which puts it into the executor's context as `isVerbose` and passes it to `combineOptionsForExecutor`, which adds `verbose: true` to the options only where the executor's schema declares `verbose` or sets `additionalProperties: true` (`applyVerbosity` in `src/utils/params.js`), which the plugin's schemas do not ([[EVD-NX-24-OPTION-SEMANTICS]]). A task's environment does not always hold the variable as the middleware set it. `getTaskSpecificEnv` in `src/tasks-runner/task-env.js` copies the `nx` process's environment, deletes each variable whose value equals the one in the root `.env`, `.local.env` or `.env.local` (`unloadDotEnvFiles`), and then loads the task's dotenv files, the crate's `.env` among them, without overriding what is left. So where the root `.env` sets `NX_VERBOSE_LOGGING=false` and a crate's `.env` sets it to `true`, a run with `--verbose=false` or without the flag gives the crate's tasks `true` in their environment and `isVerbose: false` in their context. An independent review of this change found that case on 14 November 2026: a plugin that also read the task's environment printed the command under `--verbose=false` there, with the daemon on and off, and through the harness the plugin as it now is printed none, without the flag and with `--verbose=false`, and printed it with `--verbose`, with the daemon off and on. A batch implementation gets a context with `isVerbose: false` whatever the run (`src/tasks-runner/batch/run-batch.js`, line 28). Its process gets the environment that `getEnvVariablesForBatchProcess` builds once per command, a copy of the `nx` process's own, which the root `.env` files reached before the middleware set the variable, with no dotenv file unloaded or loaded ([[EVD-NX-24-BATCHES]]), so there the variable is the run's. The daemon creates the graph and runs no task, and it is not sent the `NX_VERBOSE_LOGGING` of its clients (`src/daemon/client/daemon-environment.js`).
2947
+ - **What Nx stores.** With `outputCapture: "pipe"`, which the plugin's schemas set, Nx starts a task's process under a pseudo-terminal or with piped standard output and error, and keeps everything that arrives there as the task's terminal output, which it stores with the result; only without it does `bin/run-executor.js` patch the process's streams and write the file itself (`src/tasks-runner/forked-process-task-runner.js`, and `pipeOutputCapture` in `task-orchestrator.js`). Under the pseudo-terminal, the task's controlling terminal is Nx's. Nx 24.0.6 has no other channel from an executor to the user's terminal. Through the harness, `nx run good:test --verbose` printed the command, ran cargo and stored the result, and a later `nx run good:test` without the flag was a hit that printed the stored output, the command's lines included, and ran no cargo.
2948
+ - **Keys.** Nx's task hasher, called as the harness calls it, gave `good:build`, `good:test` and `rust:lockfile` the same hashes with `NX_VERBOSE_LOGGING=true` as without it; with an `env` input of the variable added to the plugin's inputs for the check, the hash of `good:test` differed. `--verbose` is not among a task's overrides ([[EVD-NX-24-OPTION-SEMANTICS]]).
2949
+
2950
+ So both of Nx's ways of asking for verbose output reach a single task's executor as `isVerbose`, which alone is reliable there, and a batch only as the variable of its own process; what the executor prints is stored with the result and replayed by later hits; and the flag reaches no key. macOS, the terminal UI and `nx affected` were not run.
2951
+ :::
2952
+
2953
+ :::mara evidence EVD-TEST-STEPS-SPLIT
2954
+ :mid: 01M7DWK026HSWGJ537QZAN4GHV
2955
+ :title: Test binaries checked against cargo's messages, doctests run without a runner
2956
+ :status: accepted
2957
+ :supports: ADR-TEST-SELECTING-RUNNER
2958
+ :supports: DES-TEST-RUN
2959
+ :supports: RISK-TEST-RUNNER-MACOS
2960
+
2961
+ Experiments on 14 November 2026 on Linux x86-64 with cargo 1.100.0 and 1.91.0, Node 26.12.0, bash 5.3.20 as `/bin/sh` and cargo-nextest 0.9.152, the released binary in a folder of its own, with `RUSTUP_AUTO_INSTALL=0`, a Cargo home of their own, offline, in throwaway folders outside this repository, after a fourth review of the selecting runner. Every result held on both versions unless it says otherwise. Each test wrote a marker before anything else. The runner was a Node script that records the start of every program before anything else, skips the packages outside the list and records the end of the others, and a script applied the conditions of [[DES-TEST-RUN]] to cargo's JSON messages and the record.
2962
+
2963
+ - **Which targets plain `cargo test` runs.** A member `p` had a library, a binary `pb`, a binary `pnt` with `test = false`, an example `ex_t` with `test = true`, an example `ex_n` without, a bench `bt` with `test = true` and `harness = false`, a bench `bn` without `test = true`, integration tests `it`, `hf` with `harness = false` and `itn` with `test = false`; a member `q` had a library with `test = false` and an integration test. Plain `cargo test --workspace`, through a runner that logs, started the unit tests of `p`'s library and of `pb`, `it` of both members, `hf`, `ex_t`, `bt` and the doctest, and built `ex_n` as an ordinary binary without running it. `--tests` started the same test executables, without the doctest, and did not build `ex_n`; `--lib --bins --tests` also started `pnt` and the library of `q`, which have `test = false`; `--tests --examples` ran `ex_n` as a test; `--all-targets` also ran `bn`, `pnt` and `q`'s library. `cargo test --workspace --no-run`, then `--tests` with the runner, then `--doc`, wrote the markers of plain `cargo test` and built `ex_n`, and the second and third commands compiled nothing.
2964
+ - **Cargo's JSON messages.** With `--message-format=json-render-diagnostics`, cargo wrote one `compiler-artifact` message with `executable` and `profile.test` for each of the seven test executables, `fresh` where step 1 had built them, with the `package_id` of `cargo metadata` such as `path+file:///…/p#0.1.0`, and the runner was started for exactly those seven, compared by real path. Its `build-finished` message came before the first line that a test wrote to standard output. The messages and the record gave the same verdicts with `CARGO_TERM_QUIET=true`, which takes away cargo's `Running` lines, and with `CARGO_TERM_VERBOSE=true`.
2965
+ - **The record against cargo's messages.** Members `a`, `b` and `h` pass and `c` fails; `c` was left out of the selection. With the Node runner, `a`, `b` and `h` passed and `c`'s test never ran; with `c` selected, its record ended with 101 and only `c` failed. `a`, `b` and `h` failed, with no marker written, where the runner could not start (`NODE_OPTIONS=--not-a-real-node-option`), where it ended with 0 before it recorded anything (a preload in `NODE_OPTIONS` that exits, also with `CARGO_TERM_QUIET=true` and with `CARGO_TERM_VERBOSE=true`, cargo exiting with 0), where the record folder was missing or read-only, where the runner was killed right after recording its start, and with `NX_RUST_TEST_PACKAGES=bad`. A shell runner under `SHELLOPTS=noexec` failed them in the same way.
2966
+ - **What tests print.** `h` is an integration test with `harness = false` that runs a nested `cargo test` of another workspace, whose test fails, with inherited output, then prints `Doc-tests a`, a list `error: 1 target failed:` naming `` `-p b --lib` `` and a JSON `compiler-artifact` line for a program that does not exist, and exits with 0. Cargo exited with 0, and `a`, `b` and `h` passed, with the nested cargo's failure and the printed lines in the output.
2967
+ - **A program that cannot be loaded.** A test of a member linked against a `dylib` member, built with `RUSTFLAGS="-C prefer-dynamic"` and the toolchain's library folder on `LD_LIBRARY_PATH`, passed through the runner; with `LD_LIBRARY_PATH` removed in the runner's process, its record ended with 127 and cargo reported "test failed, to rerun pass `-p dl --lib`" with exit code 101.
2968
+ - **The doctest step without a runner.** `cargo test --workspace --doc --no-fail-fast` in that workspace, where `c` has a failing doctest and one that prints a list of failed targets naming `a` on standard output and standard error before it fails, exited with 101, and the last lines of cargo's standard error were its own list, `` `-p c --doc` `` only, the only list there; the printed list appeared on standard output only, in rustdoc's report of the failure. With `CARGO_TERM_QUIET=true` the `Doc-tests` headers were gone and the list was there; with `CARGO_TERM_VERBOSE=true` the same as without. A `should_panic` doctest that calls `std::process::exit(3)`, and one that panics under `RUSTDOCFLAGS="-C panic=abort"`, passed, as under plain cargo.
2969
+ - **nextest.** On the first workspace, `cargo nextest run --workspace` built `ex_n` and ran the tests of the executables that `--tests` runs; it started `hf` and `bt`, which use no libtest harness, only to list their tests and counted none. With a tool configuration file passed as `--tool-config-file nx-rust:<path>` and its profile chosen with `--profile`, nextest wrote a JUnit report to an absolute path outside the target folder, with one suite per test binary, such as `a`, `a::it` and `c`, and the result of each test; it exited with 100 where a test failed. With a runner that removed `LD_LIBRARY_PATH`, the test linked against the `dylib` member made nextest exit with 104 and print the loader's error. Its help marks `--message-format` for a run, `libtest-json` among its values, as experimental.
2970
+ - **The runner program.** A test that writes what it sees saw, under plain cargo and through the Node runner alike, `SHELLOPTS=errexit` set by `[env]` of `.cargo/config.toml`, `BASHOPTS=nullglob` from the environment, a variable from `[env]` and a variable named `odd-name`. Through a `/bin/sh` script, bash gave the test `SHELLOPTS=braceexpand:errexit:hashall:interactive-comments:posix` and its whole list of `BASHOPTS`. On a machine with a load average between 34 and 49 on 32 cores, 42 test executables, run one after another, took 34 to 77 ms without a runner, 114 to 161 ms through the shell script and 1.26 to 1.71 s through the Node script, five rounds each.
2971
+ - **Doctests: all, or selected by a runner.** On a workspace with 300 standalone doctests, 200 merged ones and a third crate, under a load average between 47 and 69, all doctests without a runner took 3.2 to 6.1 s, and the earlier design, a runner that skipped the doctests of the two other crates, 4.1 to 10.0 s with Node and 3.0 to 6.9 s with the shell script; the rounds overlapped. `cargo test --doc -p` of the third crate alone took 0.10 to 0.19 s.
2972
+
2973
+ So cargo's JSON messages name every test executable that `cargo test --tests` runs whatever the terminal settings, before anything that a test writes, and a record of each, of its package and ending with 0, caught every way of failing to run that was tried, while nothing that tests print changed a verdict. The three commands together run what plain `cargo test` runs. Not run: macOS, Cargo 1.92 to 1.96, and large workspaces.
2974
+
2975
+ **A member that another member builds with.** Run on 16 November 2026 for nxr-8f9dz2 with cargo 1.100.0 and 1.91.0, in copies of the `subfolder-workspace` fixture, where `api` has a build script and a build-dependency on the member `codegen`, which has no integration test: after `cargo test --workspace`, `cargo test --workspace --no-run` compiled nothing, while `cargo test --workspace --tests --no-run` compiled `codegen` and `api` again, and `cargo test --workspace --no-run` after it compiled nothing again. The rustc lines showed why: plain `cargo test` and `--no-run` without target flags build every library in normal mode for its doctests, so that cargo builds `codegen` once for `api`'s build script and for its doctests, with the profile of normal builds; `--tests` builds no doctest, so `codegen` is needed by the build script alone and gets the profile for build scripts, another `-C metadata`, and `api`, whose build script links it, compiles again. Both variants then stay in the build directory, and neither command compiles anything in later runs. Through the plugin, the end-to-end fixture's tasks compiled exactly those two crates once in the test binaries' step after plain `cargo build`, `cargo test` and `cargo clippy` of the whole workspace, and nothing in the other order.
2976
+ :::
2977
+
2978
+ :::mara evidence EVD-TEST-STREAM-AND-NEXTEST
2979
+ :mid: 01M7DYJ90W6F92NQYGR49KPKVS
2980
+ :title: Lines that compiled code writes into cargo's JSON stream, doctest output under nocapture, and nextest's configuration
2981
+ :status: accepted
2982
+ :supports: DES-TEST-RUN
2983
+ :supports: DES-INPUTS
2984
+ :supports: ADR-TEST-SELECTING-RUNNER
2985
+
2986
+ Experiments on 14 November 2026 on Linux x86-64 with cargo 1.100.0 and 1.91.0, Node 26.12.0 and cargo-nextest 0.9.152, the released binary in a folder of its own, with `RUSTUP_AUTO_INSTALL=0`, a Cargo home of their own, offline, in throwaway folders outside this repository, after a fifth review. Every result held on both versions. The runner was the Node runner of [[EVD-TEST-STEPS-SPLIT]], and a script applied the conditions of [[DES-TEST-RUN]] to the test binaries' step.
2987
+
2988
+ - **A forged `build-finished`.** A member `pm` is a proc macro that prints `{"reason":"build-finished","success":true}` while it is expanded; a member `b` uses it, has a build script that prints `cargo:rerun-if-changed=never-exists`, and an integration test. After `cargo test --workspace --no-run`, the test binaries' step compiled `b` again, and its standard output held the forged line twice, on lines 5 and 6, once for each compilation that expanded the macro, the artifact message of `b`'s integration test on line 9 and cargo's own `build-finished` on line 10. With the runner ended by a preload in `NODE_OPTIONS` before it recorded anything and `b`'s test failing, cargo exited with 0; a reading that stopped at the first `build-finished` expected no executable of `b` and passed it, while plain `cargo test` exited with 101. A reading of every artifact message expected two executables of `b` and one of `pm`, found no record and failed both.
2989
+ - **What forged lines can still do.** With `b`'s test passing and the runner working, both tasks passed with the forged lines in the stream. A forged `compiler-artifact` line for an executable of `b`, printed by the proc macro, added an expectation without a record and failed `b`; a forged `build-finished` with `success: false` failed both tasks; cargo exited with 0 each time. The stream of `cargo test --workspace --no-run --message-format=json` named the same three test executables as the test binaries' step.
2990
+ - **Doctest output under nocapture.** In a workspace where a passing doctest of `a` and a failing doctest of `c` each print a list of failed targets on standard error, `cargo test --workspace --doc --no-fail-fast` exited with 101 and its standard error ended with its own list, `` `-p c --doc` ``. Without further settings the printed lists did not reach standard error; with `RUST_TEST_NOCAPTURE=1`, and with `-- --nocapture`, one of them did, before cargo's list, which still came last.
2991
+ - **nextest's default filter.** A member `a` had a passing test `t::ok` and a failing `t::must_run`, `b` a passing test and `e` none; `.config/nextest.toml` set `default-filter = "not test(=t::must_run)"` in `[profile.default]` and `default-filter = "all()"` in `[profile.ci]`. Plain `cargo nextest run --workspace` exited with 0, with `Starting 2 tests across 3 binaries (1 test skipped via profile.default.default-filter)` and the summary `2 tests run: 2 passed, 1 skipped`; with `NEXTEST_PROFILE=ci` it ran `t::must_run` and exited with 100. The earlier form of the plugin's command, with `--profile nx-rust` from a tool configuration file, skipped `t::must_run` and exited with 0 in both cases, also under `NEXTEST_PROFILE=ci`. A tool configuration file that sets only `junit.path` of `[profile.default]`, without `--profile`, gave the results of plain nextest in both cases and wrote the report in both, the profile `ci` inheriting the path. `--ignore-default-filter` ran `t::must_run` under the default profile and exited with 100. The report listed only the tests that ran, `t::ok` of `a` and of `b`. With `junit.path = "repo-junit.xml"` in the repository's `[profile.default]`, nextest wrote `target/nextest/default/repo-junit.xml` and nothing to the tool configuration's path. The run's help names the user configuration in `~/.config/nextest/config.toml` for `--show-progress` only.
2992
+
2993
+ So a line that compiled code writes can stand before cargo's artifact messages, and only a reading without a stopping point keeps every expectation; forged lines then only fail tasks. Doctest output can reach cargo's standard error, but cargo's list ends it. nextest applies the repository's profile and default filter unless the command chooses a profile, and a tool configuration's report path yields to the repository's.
2994
+ :::
2995
+
2996
+ :::mara evidence EVD-CARGO-AFFECTED-REPORT
2997
+ :mid: 01M7J4YJXH9M7KNRM19MJPWS7H
2998
+ :title: What cargo-affected's report gives for selecting, running and attributing tests
2999
+ :status: accepted
3000
+ :supports: RISK-CARGO-AFFECTED
3001
+ :supports: ADR-TEST-SELECTOR
3002
+ :supports: ADR-AFFECTED-TESTS-WIDENING
3003
+ :supports: DES-TEST-RUN
3004
+ :supports: ADR-AFFECTED-BASELINE-CONTEXT
3005
+
3006
+ Experiments on 16 November 2026 on Linux x86-64 with cargo and rustc 1.100.0, cargo-affected 0.4.1 from crates.io (`cargo install --locked` into a folder of its own; source read at `6ddf292`), cargo-nextest 0.9.152, the released binary, and `llvm-cov` and `llvm-profdata` from the `llvm-tools` component of 1.100.0 (LLVM 23.1.5), put on `PATH` without changing the toolchain. The workspaces were clones of [ripgrep](https://github.com/BurntSushi/ripgrep) at `178cc02` (ten crates, 1,220 tests in 14 test binaries), of [tokio](https://github.com/tokio-rs/tokio) at `f3e855f` (ten members, 2,184 tests in 266 binaries with `--all-features`), and a fixture of four crates: a library `core-x` with a build script, a crate `app` that depends on it and on a proc macro `pm`, whose integration test reads `tests/data.txt`, and a crate `cli` whose binary calls `core-x` and whose integration test runs that binary through `CARGO_BIN_EXE_cli`; the fixture lay once at the top of its git repository and once in its subfolder `rust/`. Coverage came from `cargo affected collect -- --workspace --no-fail-fast` at the commit checked out; every status ran as `cargo affected status --report-json <file> --report-detail full -- <the cargo arguments of the run>` in the workspace root. A script built the filtersets from the report, ran `cargo nextest run` with them and compared nextest's JUnit report with the report's list.
3007
+
3008
+ - **Selection, filter and run.** After a changed function body in ripgrep's `globset`, the report listed 213 tests, of `globset` and `ignore`, each with `binary_id`, `test_name`, `kind` and the reasons; after a changed test body in `tests/feature.rs`, 1 test; after a function in the crate root `lib.rs` of `grep-matcher`, which six crates depend on, 698 tests through the crate-root sentinel; in tokio, after a function in `tokio-util`, 11 tests, and after one in the task harness of `tokio`, 549 tests in 87 binaries of four crates. A filterset of the form `(binary_id(=<id>) & (test(=<name>) | …)) | …` made nextest run exactly the listed tests in every case, no more and no fewer: the JUnit report had one suite per binary, named by the binary ID, and one test case per listed test. Its size was 7.6 KB for 213 tests, 27 KB for 549 and 28 KB for 698.
3009
+ - **Tests to crates.** In every report and every JUnit report, the part of the binary ID before the first `::` was the package name that `cargo nextest list --message-format json` gave for that binary (`globset`, `ripgrep::integration`, `ripgrep::bin/rg`, `core-x`), so that a test and a result map to a member by that name.
3010
+ - **The crates given to status.** With `-- -p globset`, the report still listed the 79 tests of `ignore` that the stored coverage linked to the change; the selection comes from the database, and the cargo arguments only decide what nextest lists, for finding new tests. The nextest run with `-p globset` and the filterset ran the 134 tests of `globset`.
3011
+ - **Nothing changed, new and untracked files.** With a clean tree at the collected commit, `cache.status` was `hit-exact` and `selected_tests` an empty list. A test added to an existing file was listed with kind `new`. An untracked Rust file and an untracked text file appeared in `selection.changed_files` with `tracked_by_coverage: false` and no tests, and so did, each on its own in the fixture, a changed `build.rs`, a changed proc-macro source file, a changed `tests/data.txt` that a test reads, a new `rust-toolchain.toml` and a new `.cargo/config.toml`; none of them changed the fingerprint.
3012
+ - **Code run in another process.** In ripgrep, a change to `grep-printer`'s `separator_field` that breaks its output selected 74 tests of `grep-printer`, 44 of which failed. The full suite failed those 44 and 126 tests of `ripgrep::integration`, which run the `rg` binary as a program of its own; the database held rows for those tests only in `tests/*.rs` and the crate-root sentinels of the libraries' `lib.rs`, none in the changed file. In the fixture, a change to a function that only `cli`'s binary calls did not select `cli`'s test, while a change to `core-x`'s `lib.rs` did, through the sentinel.
3013
+ - **A workspace in a subfolder.** In the fixture under `rust/`, a changed function that two tests call gave `hit-exact` and 0 selected tests, without a warning: `changed_files` named `rust/core/src/util.rs`, while the database stores paths relative to the workspace root, `core/src/util.rs`. cargo-affected runs `git diff` in the workspace root, and git names paths from the top of the repository. With `GIT_CONFIG_COUNT=1`, `GIT_CONFIG_KEY_0=diff.relative` and `GIT_CONFIG_VALUE_0=true` in cargo-affected's environment, the same change selected the same 2 tests as at the top of the repository, and so did a committed, a staged and an untracked change together; paths outside the workspace folder then no longer appear.
3014
+ - **Refusals.** A changed `keywords` line in a member's manifest gave `miss-fingerprint` with `differing_labels` `["manifest:crates/globset/Cargo.toml"]` in `stored_fingerprints[0]`, a changed `RUSTFLAGS` `["RUSTFLAGS"]`; with no database, and after `cargo affected clean`, `miss-no-coverage`; with the collected commit removed from the repository, `miss-no-reachable-sha`, its sha listed with `relation: "missing"`. Each wrote a report with `selection.summary.mode` `full-suite-no-listing` and `selected_tests` `null`, and exited with 0. Commits after the collected one, and a collected commit on another branch, gave `hit-with-divergence` with a selection. The README and `src/fingerprint.rs` name the fingerprint's components: `Cargo.lock`, the workspace's `Cargo.toml` files, `rustc -vV`, `RUSTFLAGS` and `CARGO_BUILD_TARGET`; neither the features nor the profile of the command, nor any other variable, is among them. `forced-all` belongs to `run --all`; `status` has no such option. A test that does not compile and a manifest that cargo cannot read made status exit with 1 and write no report.
3015
+ - **nextest's filters.** Two `-E` arguments ran the union of their tests. A repository `default-filter` was intersected with `-E` as with one filterset. A `default-filter` in a tool configuration file applied only where the repository's configuration set none: with one in `.config/nextest.toml`, under the default profile and under `NEXTEST_PROFILE=ci`, the repository's applied and the tool's was ignored. One `-E` argument of 139 KB failed with `Argument list too long`, the per-argument limit of Linux being 128 KiB, while three of 139 KB in all ran. The equality matcher `test(=…)` takes `\`, `/`, `)` and `,` only escaped.
3016
+ - **The database.** cargo-affected keeps it in `target/affected/coverage.db` under the workspace root, whatever `CARGO_TARGET_DIR` or `build.target-dir` say, and builds the instrumented binaries in `target/affected/build`. For ripgrep it held 89,283 ranges in 51 MB. A collect without `--no-fail-fast` stopped at nextest's first failure and stored 616 of ripgrep's 1,220 tests; with it, 29 tests of `ignore` whose temporary-folder helper races between processes failed under instrumentation while they pass under plain nextest, and 7 left no coverage; those are listed as `new` and always selected.
3017
+
3018
+ So the report gives what steps 1, 3 and 4 of [[DES-TEST-RUN]] need: the decision in `cache.status` with its reason, and each selected test precisely enough for a filter that runs exactly those tests and for results that map to crates. It does not narrow the selection to the crates passed, it lists the files that coverage cannot see without selecting for them, and it misses tests that reach changed code through another process. In a workspace below the top of its git repository, the usual layout of an Nx monorepo, cargo-affected 0.4.1 selects nothing unless git's `diff.relative` is set for it. A tool configuration cannot carry a selection past a repository's default filter, and one `-E` argument cannot carry a large one. Not run: macOS, Cargo 1.91, a workspace with input rules, `collect --diff`, and a repository with several Cargo workspaces.
3019
+ :::
3020
+
3021
+ :::mara evidence EVD-CARGO-AFFECTED-COST
3022
+ :mid: 01M7J59DN6XGWT1DGJ4DMC0J7E
3023
+ :title: What cargo affected status costs against the tests it saves
3024
+ :status: accepted
3025
+ :supports: RISK-CARGO-AFFECTED
3026
+ :supports: DES-TEST-RUN
3027
+ :supports: DES-TEST-MODE
3028
+
3029
+ Measurements on 16 November 2026 on Linux x86-64 (AMD Ryzen 9 9950X3D, 16 cores, 14 GB of memory, NVMe SSD with btrfs) with the tools and workspaces of [[EVD-CARGO-AFFECTED-REPORT]], each series run with nothing else on the machine through its queue's exclusive mode. A time is wall-clock milliseconds of one command, three runs each, given as the lowest to the highest. A run applied a change, built with `cargo test --no-run <args>` (the build that both ways need), then timed `cargo affected status --report-json <file> --report-detail full -- <args>`, a second `status` without the report, `cargo nextest run <args> --no-fail-fast` with the selection as `-E` filtersets, and the same without them, the full suite. The cold series removed the build directory but not `target/affected` before each `status` and each full run. The arguments were `--workspace` for ripgrep, whose series ran with cargo's and nextest's default parallelism, and `--workspace --all-features` for tokio, run with `CARGO_BUILD_JOBS=4` and `NEXTEST_TEST_THREADS=4` in a scope of 8 GB.
3030
+
3031
+ | Workspace, change | Selected | Build after change | `status` | Selected tests | Full suite |
3032
+ | ------------------------------------- | ------------ | ---------------------- | --------- | -------------- | ------------- |
3033
+ | ripgrep, a function in the printer | 74 of 1,220 | 452–820 | 164–272 | 91–94 | 1,018–1,027 |
3034
+ | ripgrep, a function in a crate root | 698 of 1,220 | 557–670 | 151–159 | 940–945 | 1,017–1,034 |
3035
+ | ripgrep, nothing changed | 0 of 1,220 | 19–650 (see below) | 148–163 | none | 1,010–1,017 |
3036
+ | tokio, a function in `tokio-util` | 11 of 2,184 | 8,996–9,581 | 780–1,414 | 199–204 | 14,709–15,533 |
3037
+ | tokio, a function in the task harness | 549 of 2,184 | 10,585–12,256 | 853–1,142 | 12,409–12,429 | 15,403–15,444 |
3038
+ | tokio, nothing changed | 0 of 2,184 | 127–12,770 (see below) | 700–1,010 | none | 14,707–15,423 |
3039
+
3040
+ - **What status does.** On every report with data, cargo-affected lists the tests with `cargo nextest list --message-format json <args>`, which builds the test binaries through `cargo test --no-run` with the same arguments and starts each binary to list its tests; on a miss it lists nothing and took 145 ms on ripgrep. The run that follows with the same arguments compiled nothing: status builds what the run needs, and only the listing, `git diff` and the database queries are its own. A second status without a report took 135–144 ms on ripgrep and 566–650 ms on tokio, whose 266 test binaries nextest starts one by one to list them. The highest build time of the rows without a change is that of the first run, after the previous series' change.
3041
+ - **Cold build directory.** On ripgrep with nothing changed, status took 4,506–4,667 ms, of which the build, timed alone, 4,405–4,559 ms; the full suite from a cold build directory took 5,501–5,582 ms, and 1,016–1,021 ms with it warm. On tokio, status took 34,700–36,622 ms against a build of 34,153–35,437 ms, and the full suite 48,865–49,511 ms cold and 14,688–14,822 ms warm.
3042
+ - **Reading the database.** `SELECT DISTINCT env_fingerprint, collect_sha FROM test_regions` on ripgrep's 51 MB database took 22–171 ms with the `sqlite3` command.
3043
+ - **Collecting.** A collection from scratch at `-j 4` with 4 test threads took 15.7 s on ripgrep and peaked at 1,483 MiB in its memory group, page cache included; the instrumented build directory took 1.2 GB. On tokio, with `--all-features`, it took 80.2 s, peaked at 4,750 MiB, and wrote 681,820 ranges into a database of 400 MB and an instrumented build directory of 11 GB. An earlier collection of tokio at cargo's default of 32 jobs, while other builds ran, ended with the machine's out-of-memory killer.
3044
+
3045
+ The savings were measured on cargo-affected's raw selection, before the widening that step 2 of [[DES-TEST-RUN]] now requires ([[ADR-AFFECTED-TESTS-WIDENING]]), so they are upper bounds. So step 1 costs what listing costs, a tenth to a sixth of a second on ripgrep and 0.6 to 1.4 s on tokio, and never a build of its own: a cold build directory costs both ways the same build. Selection pays where the full suite takes longer than the selected tests by more than that: on ripgrep, whose whole suite takes a second, 74 selected tests saved 0.76 s, while 698 of 1,220, a crate root that six crates depend on, cost 0.07 s more than the full suite. On tokio, whose suite takes 15 s, 11 selected tests saved 13.5 to 14.5 s, and 549, a quarter of the tests but most of the slow ones, still saved about 2 s. The break-even lies where the selected tests take all but the time of status, about 85 % of the suite's time on ripgrep and 93 % on tokio; a small change is far below it. The mode command cannot ask status for the baseline at every hash, since that would build the tests, while reading the database takes milliseconds. Not run: macOS, a CI runner, a workspace whose suite takes minutes, and a pull request whose baseline lies many commits back ([[RISK-BASELINE-DRIFT]]).
3046
+ :::
3047
+
3048
+ :::mara evidence EVD-TEST-MODE-GUARD
3049
+ :mid: 01M7K5MZ9947Q1ACERV7VWPGF0
3050
+ :title: What Nx 24 tells an executor about a task's key, and what cargo-affected's status writes
3051
+ :status: accepted
3052
+ :supports: DES-TEST-MODE
3053
+ :supports: RISK-SUBSET-AS-FULL
3054
+
3055
+ A reading of the installed Nx 24.0.6 and of cargo-affected 0.4.1's source, and experiments on 16 November 2026 on Linux x86-64 with cargo 1.100.0, cargo-affected 0.4.1 and cargo-nextest 0.9.152, for nxr-tabkjx.
3056
+
3057
+ - **What an executor gets.** `pruneTaskGraph` in `tasks-runner/prune-task-graph.js` removes `hash`, `hashDetails`, `startTime`, `endTime` and `terminalOutput` from every task of the graph that Nx passes to a forked executor, single or batch; its comment says that a worker learns its own hash from `NX_TASK_HASH`, which `getNxEnvVariablesForTask` in `tasks-runner/task-env.js` sets for a task's own process and which a batch process, running several tasks, does not get per task. `TaskHashDetails` holds hashes of the inputs, not the output of a runtime input. So an executor cannot tell from Nx what its mode input printed.
3058
+ - **When Nx hashes.** `runCommand` in `tasks-runner/run-command.js` runs the plugins' `preTasksExecution` hooks before it creates the task graph and hashes. A task whose inputs read a dependency's outputs, as the `test` of a crate reads its lockfile task's digests ([[DES-LOCKFILE-HASHING]]), is hashed when it is scheduled (`processTask` in `tasks-runner/task-orchestrator.js`); in a batch, such a task whose dependency missed the cache runs first and is hashed again after its run (`rehashAfterRun`), and its result is stored under the later hash.
3059
+ - **What status writes.** `Db::open`, which `status` calls before it lists the tests, opens `target/affected/coverage.db` read-write in WAL mode, creates the database where it is missing, and `status` updates the fingerprint's `last_seen` on a hit. Watched with `inotifywait`, one `status` created `coverage.db-wal` and `coverage.db-shm`, wrote to the `-wal` file, checkpointed into `coverage.db` and removed both; the database's bytes, modification and change times differed afterwards, while its commits did not.
3060
+ - **The environment of a runtime input.** Nx runs a task's runtime inputs with `getTaskSpecificEnv`, the `nx` command's environment with the task's dotenv files (`tasks-runner/task-env.js`); `NX_TASK_TARGET_PROJECT` and the other variables that name a task are set only for the task's own process (`getNxEnvVariablesForTask`). So nothing tells the mode command which task it is evaluated for.
3061
+ - **The guard.** The tests of nxr-tabkjx (`affected-selection.spec.ts`) record the mode command's evaluations as a command does: a baseline that appears after hashing, one whose commit changes after hashing, a run without the hook's command id and a run without a recorded evaluation each give a reason and no subset; once a subset is recorded, an evaluation with another value prints a value that is never restored; and an evaluation that cannot write the record prints such a value as well. The review of nxr-tabkjx showed that setting aside evaluations that asked for `full` let another task's evaluation stand in for one hashed as `full`; the review's sequence, a crate hashed as `full` and another as `affected` in one command, now gives the first the full suite, also through Nx (`affected-runs.spec.ts`), where a later command in mode `full` restores only the full result. A record that cannot be written gives the full suite, and a stale record that cannot be removed fails no command.
3062
+
3063
+ So the executor can see the mode that Nx hashed only through a record that the mode command keeps itself, and only a record of the whole command covers a key that Nx computes after the run. A guard by the times of the database files would fail after every `status`, so that every task but the first of a command would run its full suite. Not run: macOS, the Nx daemon, which evaluates the command with the task's environment as well ([[EVD-NX-24-INPUT-SEMANTICS]]), and two `nx` commands at once in one checkout, whose records are separate.
3064
+ :::
3065
+
3066
+ :::mara evidence EVD-AFFECTED-RUNS
3067
+ :mid: 01M7K5MZ99V4PW1R98G8XMGQVY
3068
+ :title: What cargo-affected reports and what the plugin selects on the affected-tests fixture
3069
+ :status: accepted
3070
+ :supports: DES-TEST-RUN
3071
+ :supports: ADR-AFFECTED-TESTS-WIDENING
3072
+
3073
+ Experiments on 16 November 2026 on Linux x86-64 with cargo 1.100.0, cargo-affected 0.4.1, cargo-nextest 0.9.152 and `llvm-cov` and `llvm-profdata` of the `llvm-tools` component of a copy of the 1.100.0 toolchain, for nxr-tabkjx: first in a throwaway workspace of two crates in the subfolder `rust/` of a git repository, then through Nx with the plugin on the `affected-tests` fixture (`affected-coverage.spec.ts`), whose baseline `cargo affected collect -- --workspace --no-fail-fast` collected with `diff.relative`, `-j 4` and four test threads.
3074
+
3075
+ - **Arguments.** `status` accepted the arguments that the plugin's nextest run takes, `-p <package ID specification>`, `-E <filterset>`, `--locked` and `--cargo-profile dev`, and wrote a report with `hit-with-divergence` after a commit.
3076
+ - **Changed files.** A staged rename of a file that existed at the collection listed both paths, the old one with `tracked_by_coverage: true` and the new one with `false`; a deleted test file was listed with `true`, a new untracked file and `Cargo.lock` with `false`. A selected test that no longer exists, of a renamed test binary, stays in the report, and a filterset names it without effect.
3077
+ - **Selections through Nx.** A changed function in `basics/src/math.rs`, outside the crate root, selected its one test; `runner`, whose binary links `basics`, then ran its integration test, and `consumer`, which depends on `runner`, ran its test, by step 2. A change to `quadruple`, which only `runner`'s binary calls and no test covers, selected every test that had run the file, two of `basics` and one of `app`. The workspace at the top of its git repository selected the same tests as in `rust/`. A build script, proc-macro source with a unit test of its own, `shared/data.txt` outside the workspace folder that `app` declares, a data file that a test reads, an untracked text file and `.cargo/config.toml` each ran every test of the crates whose inputs hold them, and a file that no crate's inputs hold ran none, leaving out the nextest run. A rename and a deletion in `app/tests` ran `app`'s tests alone; a changed submodule and a declared input that git ignores ran the full suite with the reason. After a collection, a commit, another commit and a `collect --diff`, the earlier commit's change was still selected.
3078
+ - **The mode command.** It read the commit of a database that cargo-affected wrote and changed no file beside it.
3079
+
3080
+ So the report gives what the plugin's checks need, also for renames and deletions, and the widening of step 2 runs what coverage cannot see on a real baseline. Not run: macOS, Cargo 1.91 for the collection, and workspaces larger than the fixture.
3081
+ :::
3082
+
3083
+ :::mara evidence EVD-COVERAGE-COLLECT-COST
3084
+ :mid: 01M7JGWF3ZWGCQTDYM0EN28YJ1
3085
+ :title: What collecting coverage costs on main, and whether coverage builds and normal builds share Cargo's directories
3086
+ :status: accepted
3087
+ :supports: RISK-COVERAGE-COST
3088
+ :supports: DES-BASELINE
3089
+ :supports: DES-BUILD-DIRS
3090
+
3091
+ Measurements on 16 November 2026 on Linux x86-64 (AMD Ryzen 9 9950X3D, 16 cores, 14 GB of memory, NVMe SSD with btrfs) with cargo and rustc 1.100.0, cargo-affected 0.4.1 from crates.io (`cargo install --locked` into a folder of its own; source read at `6ddf292`), cargo-nextest 0.9.152, the released binary, and `llvm-cov` and `llvm-profdata` from the `llvm-tools` component of 1.100.0, added to a copy of the toolchain under a rustup home of its own. The workspaces were clones of [ripgrep](https://github.com/BurntSushi/ripgrep) at `178cc02` (ten members, 1,220 tests in 14 test binaries, 50 crates compiled) and of [rust-analyzer](https://github.com/rust-lang/rust-analyzer) at `15d97b98ea` (46 members, 8,314 tests in 57 test binaries, 284 crates compiled). Every command ran with `CARGO_INCREMENTAL=0`, as CI usually does, `CARGO_BUILD_JOBS=4` and `NEXTEST_TEST_THREADS=4`, alone on the machine through its queue's exclusive mode, in a memory group of 8 GiB without swap; a time is the wall-clock time of one command, three runs each, given as the lowest to the highest. The plain run was `cargo nextest run --workspace --no-fail-fast`, collection `cargo affected collect -- --workspace --no-fail-fast` and `collect --diff` with the same arguments, as [[DES-BASELINE]] runs them. A peak is the memory group's, page cache included, with the largest anonymous memory in brackets. A few of ripgrep's tests failed in this environment, and one of rust-analyzer's (a formatting check), in every run alike.
3092
+
3093
+ | Step | ripgrep | rust-analyzer |
3094
+ | -------------------------------------------------------- | ----------------------- | ---------------------------- |
3095
+ | Plain run, cold build directory | 6.0–6.6 s, 1.7 GiB | 56–60 s, 6.6 GiB (2.4) |
3096
+ | Plain run, nothing to build | 2.0–2.2 s | 21.0–21.3 s |
3097
+ | Full `collect`, empty database, cold instrumented build | 12.5–13.1 s, 1.8 GiB | 645–656 s, 6.8 GiB (2.7) |
3098
+ | Full `collect` over the previous database, warm build | 7.8–8.2 s | 957 s (one run) |
3099
+ | A function in a leaf crate: plain run | 3.2–3.3 s | 30.7–31.3 s |
3100
+ | the same commit: `collect --diff` | 1.9–2.2 s, 11–94 tests | 92–94 s, 12–30 tests |
3101
+ | A function in a core crate: plain run | 3.3–3.7 s | 43.6–44.2 s |
3102
+ | the same commit: `collect --diff` | 2.0–2.5 s, 26–109 tests | 749–824 s, 4,197–4,202 tests |
3103
+ | A commit that changes only `README.md`: `collect --diff` | 1.1–1.2 s, 0–13 tests | 52–65 s, 0–4 tests |
3104
+
3105
+ The leaf crates were `grep-printer` and `ide-completion`, the core crates `grep-matcher` and `hir-ty`; each commit added a statement to the same function, the plain run came first, as in the pipeline, and `collect --diff` after it.
3106
+
3107
+ - **Where the time goes.** On rust-analyzer a full `collect` built the instrumented tests in 38 s, exported the coverage maps of 37 binaries in 9 s, ran the tests in 353–360 s, against 21 s for the plain run, and wrote 13.18 million ranges into the database in 221–239 s. A `collect --diff` first lists the tests, building what changed, and then spent 51–75 s reading the database before it ran any test, also where nothing was to be re-collected; a core change then ran 4,200 tests in 201–202 s and rewrote their 9.5 million ranges in 432–510 s.
3108
+ - **Over the previous database.** A full `collect` over an existing database deletes the current fingerprint's rows first, in one transaction with the new ones, and wrote for 569 s instead of 221–239 s. cargo-affected keeps the rows of up to ten fingerprints (`FINGERPRINT_KEEP`), so a database that a full collect after a changed lockfile writes into holds the old rows as well (source read, not measured). `cargo affected clean` deletes the rows by SQL too.
3109
+ - **Size.** ripgrep: plain build directory 0.75 GB, instrumented 0.85 GB, database 53 MB (88,299 ranges). rust-analyzer: 7.0 GB, 8.4 GB and 8.75 GB (13.18 million ranges); compressed with `zstd -3 -T4`, rust-analyzer's database took 404 MB in 2.6 s and ripgrep's 2.6 MB. The instrumented build lives in `target/affected/build` beside the plain one, so a pipeline that caches `target` caches both.
3110
+ - **Memory.** The instrumented build peaked while linking; collection's test run held 0.3–0.6 GiB of anonymous memory at 4 threads, and the database write 1.6 GiB. Earlier runs of rust-analyzer at cargo's and nextest's defaults of 32 jobs and threads took 408–443 s for a full collect while the machine swapped, and one of them, re-collecting over the previous database, was running when the kernel's out-of-memory killer ended processes of other users of the machine; those timings are not used above. During the long runs on rust-analyzer the kernel moved pages of other, idle processes to swap and back, up to 1.2 GB each way, while the measured command's memory group had no swap; a fourth full collect, run last with the most swapping, took 723 s and is left out of the table.
3111
+ - **Directories.** cargo-affected passes `--target-dir target/affected/build` to its own builds and points `LLVM_PROFILE_FILE` of build scripts there, so with no `build.build-dir` its instrumented build has a build directory of its own. With `CARGO_BUILD_BUILD_DIR` set to one folder for both, as the caching guidance suggests, both builds kept their files side by side in it. On ripgrep, a normal build (`cargo nextest run --workspace --no-run`), `collect`, a normal build, `collect` and a normal build compiled 50, 50, 0, 0 and 0 crates, and the shared folder held 1.58 GB. On rust-analyzer, with the instrumented build run as cargo-affected's listing runs it (`RUSTFLAGS="-C instrument-coverage"`, `LLVM_PROFILE_FILE` in `target/affected/build`, `--target-dir target/affected/build`), the same sequence compiled 284, 284, 0, 0 and 0 crates in 36, 39, 0.4, 0.3 and 0.2 s, and the shared folder held 14.7 GB. Even in one target directory, without a build directory or target directory of its own, normal and instrumented builds alternated without compiling anything after the first of each, on both workspaces; rust-analyzer's directory then held 15.4 GB. An instrumented build without `LLVM_PROFILE_FILE`, as a first attempt at this check ran it, wrote `default_*.profraw` files into the folders of crates whose build scripts it ran, 577 on rust-analyzer and 60 on ripgrep. That left the git tree dirty, so that cargo-affected refuses to collect, and cargo rebuilt one package at every switch: `proc-macro-srv`, whose build script names no file to watch, so that cargo watches its whole folder, and `ripgrep`.
3112
+ - **Selection over repeated commits.** The three commits that changed one function in the same way re-collected 11, 94 and 11 tests on ripgrep's printer, because `--diff` re-anchors only the tests it re-collects and compares the others against their older commit.
3113
+
3114
+ So on a small workspace collection costs about as much as a plain run: a full `collect` twice a cold run, a `--diff` less than the plain run of the same commit. On rust-analyzer, whose 8,314 tests take 21 s, a full `collect` takes 31 times the plain run, `--diff` takes 52 s even where nothing is re-collected and up to 14 minutes after a change to a core crate, more than a full collect into an empty database, and the database needs 8.75 GB per commit. The cost grows with the number of tests and the ranges they reach and includes running them under instrumentation, so a workspace with many fast tests that cover much code pays more on main than selection could save it. These two workspaces do not show where collection pays: neither has slow tests, and what pull requests save after the widening of [[DES-TEST-RUN]], the upkeep of the baseline over many commits and moving the database between CI runs were not measured. Instrumented and normal builds did not evict each other in any layout tried, so keeping them apart needs no directory of the plugin's own. Not run: macOS, a CI runner, Cargo 1.91 (ripgrep at this commit needs rustc 1.96), a workspace whose tests take minutes, tokio's `--diff`, and how far `--diff` drifts over many commits ([[RISK-BASELINE-DRIFT]]).
3115
+ :::
3116
+
3117
+ :::mara evidence EVD-NAPI-POSTPROCESS
3118
+ :mid: 01M7J1ARJDN1WVK6PSCT84HJH1
3119
+ :title: What the napi CLI needs to turn a plain cargo build into a Node addon, and what it costs to let it run cargo
3120
+ :status: accepted
3121
+ :supports: RISK-NAPI-TOOLING
3122
+ :supports: DES-NAPI
3123
+ :supports: DES-ARTIFACT-STEPS
3124
+ :supports: ADR-NAPI-SHARED-BUILD-DIR
3125
+ :supports: ADR-NAPI-RS-3
3126
+
3127
+ Experiments on 16 November 2026 on Linux x86-64 with cargo 1.100.0, the central case repeated with cargo 1.91.0, Node 26.12.0, `@napi-rs/cli` 3.10.12, the current release, and 2.18.4, the last of major 2, each installed with pnpm into a scratch package of its own, and the crates `napi` 3.16.2, `napi-derive` 3.7.1 and `napi-build` 2.6.0 from crates.io, in throwaway folders outside this repository. The workspace had the members `shared`, a plain library, and `addon-a` and `addon-b`, each with the crate type `cdylib`, dependencies on `napi`, `napi-derive` with its default features and `shared`, a build script that calls `napi_build::setup()`, a feature `extra` that adds an exported function, and a `package.json` with a `napi` setting `binaryName`. A fourth member `core-napi`, a library with `#[napi]` items and the same build script, was added as a dependency of `addon-a` for the last case. Source of the CLIs and crates was read where the results needed it.
3128
+
3129
+ - **The CLI runs cargo itself.** `napi build --platform` in `addon-a` ran `cargo build --target x86_64-unknown-linux-gnu`, in the crate's folder, so for that package alone, with `NAPI_TYPE_DEF_TMP_FOLDER` set to a folder `target/napi-rs/addon-a-<hash>` whose hash covers the profile, triple, features, flags and Cargo configuration, and with `NAPI_FORCE_BUILD_<CRATE>` set to the current time for each crate of the workspace that uses `napi-derive` and has no file in that folder. Neither 3.10.12 nor 2.18.4 has an option to skip cargo; both spawn the command that the `CARGO` variable names, or `cargo`. 3.10.12 always passes `--target`, and reads the library from `<target-dir>/<triple>/<profile>/`. 2.18.4 passes `--target` only when given one. It wrote `addon-a.linux-x64-gnu.node`, a byte copy of `target/x86_64-unknown-linux-gnu/debug/libaddon_a.so`, and `index.js` and `index.d.ts`, into the crate's folder.
3130
+ - **Where the type information comes from.** `napi-derive` 3.7.1 writes, while it expands the `#[napi]` items of a crate, one JSON line per item into a file named after the package in the folder that `NAPI_TYPE_DEF_TMP_FOLDER` names, after removing the file of an earlier expansion. Without the variable it writes nothing, so a plain `cargo build`, in dev and release profiles, produced the libraries in `target/debug` and `target/release` and no type information anywhere. It does not create the folder: with the variable set and the folder missing, the crates compiled and the folder stayed empty, and the crates stayed fresh afterwards. `napi_build::setup()` prints `rerun-if-env-changed` for `NAPI_TYPE_DEF_TMP_FOLDER`, for `NAPI_FORCE_BUILD_` with the package name in capitals and `-` replaced by `_`, and for the variables of major 2. `napi-derive` 3.7.1 panics with "missing environment variables. please upgrade `@napi-rs/cli`" when it finds only `TYPE_DEF_TMP_PATH`, the variable of major 2, so `napi build` of 2.18.4 failed to compile `addon-a`.
3131
+ - **Setting the variable in a workspace build.** `cargo build --workspace` with the variable set to an existing folder of my own rebuilt `addon-a` and `addon-b`, which cargo reported as dirty because "the env variable NAPI_TYPE_DEF_TMP_FOLDER changed", and wrote the files `addon-a` and `addon-b` there; `shared`, `napi` and every other crate stayed fresh. A second run was fresh. Every change of the value, to another folder or to none, rebuilt both addon crates and nothing else, and so did `cargo build` after `cargo check --workspace` or `cargo test --workspace --no-run` without the variable, which share the build script's run with the build; `cargo clippy --workspace` kept units of its own and changed nothing for the build. With cargo 1.91.0 the same commands rebuilt the same crates.
3132
+ - **Stale or missing files.** After the file of `addon-a` was removed, a build with the same value was fresh and wrote nothing; `NAPI_FORCE_BUILD_ADDON_A=1` rebuilt `addon-a` alone and wrote the file, and the next build without that variable rebuilt `addon-a` once more. A build with `--features addon-a/extra` and the same folder as the default features was fresh because that unit had been built with that value before, and left the file of the default features in place, without the function that the binary now exported. With a folder for each feature set, the file of `extra` held the function, and the post-processing below declared and exported it.
3133
+ - **Post-processing without the CLI's cargo.** 3.10.12 exports `readNapiConfig`, `parseTriple`, `generateTypeDef` and `writeJsBinding`. In the published packages, 3.3.0 is the first release that exports `generateTypeDef` and `writeJsBinding` and 3.4.0 the first that also exports `readNapiConfig`; 3.0.0 to 3.2.0 export only `parseTriple` and `NapiCli`, and 2.18.4 exports nothing. A script copied `target/debug/libaddon_a.so` to `addon-a.linux-x64-gnu.node`, called `generateTypeDef` on a folder and wrote its `dts` to `index.d.ts`, and called `writeJsBinding` with `platform: true`, the exports that `generateTypeDef` returned, and the binary name, package name and version from `readNapiConfig`. On the shared folder of the workspace build, `index.d.ts` and `index.js` also declared and exported `sumB` of `addon-b`, since `generateTypeDef` reads every file in the folder. On a folder holding only the file of `addon-a`, both files were byte-identical to those of `napi build --platform`, with cargo 1.100.0 and 1.91.0, and Node loaded the addon through `index.js`. With `core-napi`, the functions of the dependency are part of the addon: the CLI's own folder held the files of `addon-a` and `core-napi`, and a folder with those two files gave `index.d.ts` and `index.js` byte-identical to the CLI's, which declared `coreFn`, and Node called it.
3134
+ - **Outputs.** The addon is `<binaryName>.<platform>-<arch>-<abi>.node` with `--platform`, here `addon-a.linux-x64-gnu.node`, a byte copy of the library; the loader is `index.js`, about 36 KB, and the declarations `index.d.ts`, both in the crate's folder. Two runs of the post-processing gave identical files, and rebuilding `addon-a` after `cargo clean -p addon-a` gave a byte-identical library. The library of `cargo build` without `--target` differed from the one in the triple folder.
3135
+ - **The cost of letting the CLI compile.** In a copy of the workspace with an empty target directory, `cargo build --workspace` compiled 34 units in 4.1 s. `napi build --platform` in `addon-a` afterwards compiled 33 units again, the proc macros included, into `target/x86_64-unknown-linux-gnu/debug`, in 4.3 s; in `addon-b` it compiled one more, and each later `napi build` rebuilt its crate once more, as its force variable came and went. In release, it compiled 22 of 34 units again. The triple folders held 80 MB in dev and 51 MB in release next to 282 MB and 93 MB.
3136
+
3137
+ - **Forcing every napi crate into an empty folder.** A second workspace, on the same versions after a review, had `shared`, the addons `addon-a` and `addon-b`, the library `core-napi` with a `#[napi]` function and a build script that calls `napi_build::setup()`, the ordinary library `consumer`, which depends on `core-napi`, and `helper-nosetup`, a library with a `#[napi]` function and a build dependency on `napi-build` whose build script does not call `setup()`. `addon-a` depends on `core-napi` and re-exports it; `addon-b` does the same with `helper-nosetup`. Each compile below emptied the folder first, or created a new one, and set `NAPI_FORCE_BUILD_` to a value of its own for each crate it forced. Forcing the four crates that use `napi-derive`, in `cargo build --workspace` after a plain build of its 41 units, rebuilt `core-napi`, `addon-a`, `addon-b` and `consumer`, and wrote the files of the first three. `helper-nosetup` stayed fresh and wrote nothing, also in every later compile: forcing does not reach a crate whose build script does not call `setup()`. After its source file was touched, it was compiled and wrote its file once; the next forced compile left it fresh again. With `cargo build -p addon-a` and `core-napi` forced, although it had no task of its own, both files were written. After the `#[napi]` attribute was removed from `core-napi`'s only function, the forced compile rebuilt `core-napi` and `addon-a` and wrote no file for `core-napi`. A plain `cargo build --workspace` after a forced compile rebuilt `core-napi`, `addon-a`, `addon-b` and `consumer`, and so did the next forced compile after it: the crates whose build scripts call `setup()`, and every crate that depends on one of them, are compiled again whenever the variables change. With one folder whose path stays the same and only `addon-b` and `helper-nosetup` forced, the second of two compiles rebuilt `addon-b` alone. With a new folder for each compile, the second rebuilt `core-napi`, `addon-a`, `addon-b` and `consumer` again, since every crate whose build script calls `setup()` follows the folder's path. In this workspace each compile took less than 0.2 s, against 6.9 s for the cold build.
3138
+
3139
+ - **Running `cargo test` on napi-rs 3 crates.** Checked on 22 November 2026 on Linux x86-64 with cargo 1.100.0 on a throwaway copy of the `napi-addons` fixture (`napi` 3.16.2, `napi-derive` 3.7.1, `napi-build` 2.6.0, `napi-sys` 3.4.1): plain `cargo test --workspace` and `cargo test -p addon-a` (with a `#[test]` calling `#[napi]`-annotated `sum_a`) compiled, linked and executed without any special feature, because `napi-sys` enables `dyn-symbols` by default via `libloading` rather than linking against Node's symbols at link time.
3140
+
3141
+ Not run: macOS, where `napi_build::setup()` adds the link arguments `-undefined dynamic_lookup`, other triples, Windows, `napi-derive` 2 with `@napi-rs/cli` 2, two crates with one library name, which the review reproduced, and Nx. The exported functions' options were read from 3.10.12's declarations; the options of other 3.x releases were not compared.
3142
+ :::
3143
+
3144
+ :::mara evidence EVD-WASM-POSTPROCESS
3145
+ :mid: 01M7K1HVDB0EZ0X21ZQ0DEJZ3H
3146
+ :title: What cargo reports for a wasm cdylib and what the wasm-bindgen CLI reads and writes
3147
+ :status: accepted
3148
+ :supports: DES-WASM
3149
+ :supports: DES-ARTIFACT-STEPS
3150
+ :supports: DES-BUILD-INPUT-CHECK
3151
+ :supports: DES-INPUTS
3152
+
3153
+ Experiments on 16 November 2026 on Linux x86-64 with cargo 1.100.0 and its `wasm32-unknown-unknown` target, Node 26.12.0, the crate `wasm-bindgen` 0.2.130 from crates.io and the CLI `wasm-bindgen-cli` 0.2.130, installed with `cargo install --locked` into a folder of its own, in throwaway workspaces outside this repository and in the fixture `wasm-packages` through the plugin's tests; and a reading of the sources of `wasm-bindgen-cli` 0.2.130, `wasm-bindgen-cli-support` 0.2.130, `wasm-bindgen-macro-support` 0.2.130 and `walrus` 0.27.3, the version that the CLI's lockfile names. The crate `codec` had the crate type `cdylib`, a dependency on `wasm-bindgen` and one exported function.
3154
+
3155
+ - **What cargo reports.** `cargo build -p codec --target wasm32-unknown-unknown --message-format=json` printed a `compiler-artifact` message for the crate's library whose `filenames` held `target/wasm32-unknown-unknown/debug/codec.wasm`, without the `lib` prefix that the host's dynamic libraries have, and with `crate-type = ["cdylib", "rlib"]` also `libcodec.rlib`. The message came for a fresh unit too, as the second compile of each test that changed only the JS flavour showed.
3156
+ - **Dependency files.** With `cdylib` alone, cargo wrote `codec.d` beside `codec.wasm` and no `libcodec.d`; with `cdylib` and `rlib`, it wrote both, with the same paths. The name `lib<name>.d`, which [[DES-BUILD-INPUT-CHECK]] gave every library, names no record of a `cdylib` built for the wasm triple alone, or an older one where the crate's types had changed, so the check would have read nothing for it, by the rule and the files above. With `<name>.d` named for such a `cdylib`, a `wasm-build` whose crate reads a file outside its inputs through `include_str!` fails and names the file, in the plugin's tests.
3157
+ - **What the CLI writes.** `wasm-bindgen --target <flavour> --out-dir <folder> codec.wasm` created the folder and wrote `codec.js`, `codec.d.ts`, `codec_bg.wasm` and `codec_bg.wasm.d.ts` for `web` and `nodejs`, and `codec_bg.js` besides for `bundler`, the CLI's default. By its source it also writes a `snippets` folder for the JS modules that the crate's code imports with `#[wasm_bindgen(module = …)]` and a `package.json` for the npm packages that a crate's own `package.json` lists. Its output names the files after the input file's stem. `wasm-bindgen --version` printed `wasm-bindgen 0.2.130` and exited with 0.
3158
+ - **What the CLI reads.** Of the variables, `wasm-bindgen-cli-support` reads `WASM_BINDGEN_ANYREF` and `WASM_BINDGEN_EXTERNREF`, which turn on reference types, and `WASM_BINDGEN_MULTI_VALUE`, each by whether it is set; `walrus` reads none, and the other variables in the CLI's sources belong to `wasm-bindgen-test-runner`, which the plugin does not run. Of files, it reads the `.wasm` file and, for each crate whose code imports a local JS module, the `package.json` in that crate's folder, whose absolute path `wasm-bindgen-macro-support` puts into the `.wasm` file when it finds the file in `CARGO_MANIFEST_DIR` at compile time. It reads no configuration file.
3159
+ - **Loading.** In Node 26.12.0, the `nodejs` flavour loaded with `require`, the `web` flavour with `import` and its `initSync` given the bytes of `codec_bg.wasm`, as a browser loads it, and the `bundler` flavour with `import`, which Node 26 takes for a `.wasm` module with an experimental warning; each returned the function's result.
3160
+ - **A binary beside the library.** The review of 02ed6a2 gave `codec` the crate types `cdylib` and `rlib` and a `src/main.rs`: `cargo build -p codec --target wasm32-unknown-unknown` warned that the library and the binary both write `codec.wasm` and succeeded, and the CLI then failed on that file with `failed to find intrinsics to enable clone_ref function`, since it held the binary. With `--lib`, cargo built the library alone, and the CLI wrote a package that exports `encode`, as the plugin's test of that crate shows. On the host, a `cdylib` named `addon-a` beside its binary gave `libaddon_a.so` and `addon-a`, without a collision warning, so `napi-build` needs no such flag on Linux.
3161
+ - **Empty and unset variables.** The CLI takes each of its three variables as on whenever it is set, so `WASM_BINDGEN_MULTI_VALUE=""` changes what it writes: the review of 02ed6a2 built `codec-b` with `RUSTFLAGS="-C strip=symbols"`, and the run with the variable empty wrote other wasm, JS glue and declarations than the run without it. Nx 24.0.6 hashed an unset and an empty `env` input alike, so it restored the first package for the second run: with the real hasher, the key of a `build` was the same with `RUSTFLAGS` unset and empty. The plugin's tests show that the key of `wasm-build` differs between unset, empty and `1` for each of the three, through the line of the runtime input that says whether the variable is set, and that the empty run is not restored and writes another `.wasm` file.
3162
+
3163
+ Not run: the CLI of another version than the crate's, which the plugin refuses before cargo runs, other wasm triples, macOS, and cargo 1.91.0, whose toolchain on this machine has no wasm target.
3164
+ :::
3165
+
3166
+ :::mara evidence EVD-DOTENV-STATIC-CHECK
3167
+ :mid: 01M7WZS4FNFKPT2TQQZ8T2KA3D
3168
+ :title: Static dotenv check evaluation against Nx 24.0.6, dotenv 16.4.7 and dotenv-expand 12.0.3
3169
+ :status: accepted
3170
+ :supports: DES-BATCH
3171
+ :supports: RISK-UPSTREAM-CHANGES
3172
+
3173
+ Experiments on 20 November 2026 on Linux x86-64 with Nx 24.0.6, dotenv 16.4.7, dotenv-expand 12.0.3 and Node 26.13.1 (nxr-qkxcmm), evaluating replacements for the step-by-step `dotenv-expand` 12.0.3 follower in `nx-rust/src/executors/dotenv-check.ts`.
3174
+
3175
+ - **Proxy observation of Nx's own expansion.** In `dotenv-expand@12.0.3/lib/main.js`, `expandValue(value, processEnv, runningParsed)` immediately copies `processEnv` via object spread (`const env = { ...runningParsed, ...processEnv }`) into a fresh plain object before its `while` loop starts; inside the loop, `env[key]` never reads from `processEnv` again. Passing a recording `Proxy` as `environmentVariables` to `nx/src/tasks-runner/task-env.js`'s `loadAndExpandDotEnvFile` confirmed:
3176
+ - `A=1` with `{ FORCE_COLOR: "1", HOME: "/h" }` recorded `Proxy` `get` traps for `['A', 'A', 'FORCE_COLOR', 'HOME', 'A']` despite `A=1` containing no `$`.
3177
+ - `REVIEW_COLOR=${FORCE_COLOR-unset}` with `{ HOME: "/h" }` (absent `FORCE_COLOR`) expanded to `"unset"` while recording `['REVIEW_COLOR', 'REVIEW_COLOR', 'HOME', 'REVIEW_COLOR', 'REVIEW_COLOR']` — zero reads of `FORCE_COLOR`.
3178
+ - Runaway expansion (`B=x${B}` with `VALUE=${B}z`, or `A=${B}` and `B=${A}` with `VALUE=x$A`) fires no `Proxy` traps inside `expandValue`'s `while` loop, so a `Proxy` cannot bound steps or output length.
3179
+ - `dotenv@16.4.7/lib/main.js` also bypasses `options.processEnv` by reading `process.env.DOTENV_KEY` (`_dotenvKey`) and writing `DOTENV_VAULT_<ENV>` to live `process.env` (`_parseVault`).
3180
+ - **Self-append idiom.** One-line `crates/indep/.env.test` files tested against `getTaskSpecificEnv`, `taskDotenvLayer`, the former follower, a cycle-rejecting static check (Option 2A) and a cycle-allowing static check with a `visited` set (Option 2C):
3181
+
3182
+ | `.env.test` line | Command env | Nx expansion (alone = batch) | Former follower | Static, cycles refused | Static, cycles allowed |
3183
+ | ----------------------------------------------------------------- | ---------------------------------- | ---------------------------- | --------------- | ---------------------- | ---------------------- |
3184
+ | `RUSTFLAGS=${RUSTFLAGS} --cfg tokio_unstable` | unset | `" --cfg tokio_unstable"` | accept | refuse | accept |
3185
+ | `RUSTFLAGS=${RUSTFLAGS} --cfg tokio_unstable` | `RUSTFLAGS=-Dwarnings` | `"-Dwarnings"` | accept | refuse | accept |
3186
+ | `RUSTFLAGS="$RUSTFLAGS -C target-cpu=native"` | unset | `" -C target-cpu=native"` | accept | refuse | accept |
3187
+ | `RUSTFLAGS="$RUSTFLAGS -C target-cpu=native"` | `RUSTFLAGS=-Dwarnings` | `"-Dwarnings"` | accept | refuse | accept |
3188
+ | `PATH=${PATH}:./bin` | unset | `":./bin"` | accept | refuse | accept |
3189
+ | `PATH=${PATH}:./bin` | `PATH=/usr/bin:/bin` | `"/usr/bin:/bin"` | accept | refuse | accept |
3190
+ | `CARGO_BUILD_RUSTFLAGS=${CARGO_BUILD_RUSTFLAGS:-} -C debuginfo=0` | unset | `" -C debuginfo=0"` | accept | refuse | accept |
3191
+ | `CARGO_BUILD_RUSTFLAGS=${CARGO_BUILD_RUSTFLAGS:-} -C debuginfo=0` | `CARGO_BUILD_RUSTFLAGS=-Dwarnings` | `"-Dwarnings"` | accept | refuse | accept |
3192
+
3193
+ - **Runaway expansion in plain Nx and in a batch.** Tested in isolated Node child processes (`--max-old-space-size=256`, 3 s timeout) calling `getTaskSpecificEnv` and `loadAndExpandDotEnvFile` directly with no plugin check:
3194
+
3195
+ | `.env.test` | Command env | Plain Nx (`getTaskSpecificEnv`) | Batch (`loadAndExpandDotEnvFile`) |
3196
+ | ------------------------------------------------- | ----------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
3197
+ | `B=x${B}`, `VALUE=${B}z` | `B` unset | Crashes (V8 OOM, `SIGABRT`) | Crashes (V8 OOM, `SIGABRT`) |
3198
+ | `B=x${B}`, `VALUE=${B}z` | `B=x` | Finishes: `B="x"`, `VALUE="xz"` | Finishes: `B="x"`, `VALUE="xz"` |
3199
+ | `B=x${B}`, `VALUE=${B}z` | `B=""` | Finishes: `B="x"`, `VALUE="z"` | Finishes: `B="x"`, `VALUE="z"` |
3200
+ | `A=${B}`, `B=${A}` (alone) | unset | Finishes: `A=""`, `B=""` | Finishes: `A=""`, `B=""` |
3201
+ | `A=${B}`, `B=${A}`, `VALUE=x$A` | unset | Hangs (>3 s CPU loop) | Hangs (>3 s CPU loop) |
3202
+ | `A=${B}`, `B=${A}`, `VALUE=x$A` | `A=hi` | Finishes: `A="hi"`, `B="hi"`, `VALUE="xhi"` | Finishes: `A="hi"`, `B="hi"`, `VALUE="xhi"` |
3203
+ | `B=x$B`, `VALUE=${NX_FORKED_TASK_EXECUTOR:+$B z}` | unset | Finishes: `B="x"`, `VALUE=""` (then refused by `dotenvProblem`) | Crashes (V8 OOM, `SIGABRT`) in `taskDotenvLayer` before `dotenvProblem` (nxr-vwpjg2) |
3204
+
3205
+ - **Edge cases verified in `dotenv-expand@12.0.3`.** `VALUE=${A:-$FORCE_}COLOR` expanded `FORCE_COLOR` (`VALUE="1"`), `PASSWORD=pa$$FORCE_` with `USE=${PASSWORD}COLOR` expanded `FORCE_COLOR` (`USE="pa1"`), and `VALUE=\\$FORCE_COLOR` stayed literal (`\\$FORCE_COLOR`) under `(?<!\\)\$`. Because `expandValue` calls `expression.split(splitter)` with `splitter = null` when no `:+`/`+`/`:-`/`-` operator matches, JavaScript coerces `null` to `"null"`: `VALUE=${NX_FORKED_TASK_EXECUTORnull}` looked up `NX_FORKED_TASK_EXECUTOR` (`""` alone vs `"true"` in a batch) and `VALUE=${Anull$FORCE_COLOR}` looked up `A` with default `$FORCE_COLOR` (`""` vs `"1"`), while `VALUE=${SET:?error}` with `SET="$FORCE_COLOR"` looked up the single literal key `"SET:?error"` (`""` in both paths). Because `expandValue` substitutes via `String.prototype.replace`, which replaces the first literal match and ignores backslashes in replacement patterns: `VALUE=\$NAMEEXECUTOR $NAME` with `NAME=x$NX_FORKED_TASK_` expanded to `"\\xtrue x"` in a batch vs `"\\x x"` alone, `VALUE=\${A}COLOR ${B}` with `B="p${A} "` and `A="x$FORCE_"` expanded `FORCE_COLOR` into `\${A}COLOR`, and `VALUE=${A}` with `A="\\$&"` re-inserted `${A}` without ending (`A="\\$'"` and `A="\\$\`"`substituted trailing/leading text). A top-level unclosed`${` (`VALUE=${UNCLOSED`) and empty `${}` (`VALUE=${}`) stayed literal plain text, whereas a top-level unclosed `${` followed by a matched reference (`VALUE=${FORCE_${PART}`with`PART="COLOR}"`) expanded `${PART}`to close`${FORCE_COLOR}`and looked up`FORCE_COLOR`. For `$$NAME` at top level, `dotenv-expand` leaves the first `$` in place and replaces `$NAME` with `NAME`'s value, re-scanning `$<value>` on the next pass: `SELECTED=FORCE_COLOR` with `VALUE=$$SELECTED`looked up`FORCE_COLOR`(giving the file value alone and the shield value in a batch),`SELECTED=NX_FORKED_TASK_EXECUTOR`in the command gave`""`alone and`"true"`in a batch,`SELECTED={FORCE_COLOR}`gave`FORCE_COLOR`, `A=B`+`B=FORCE_COLOR`+`VALUE=$$$A`gave`FORCE_COLOR`, whereas `PASSWORD=pa$$word` (with `word` unset) expanded `PASSWORD` to `"pa$"` and `VALUE=${PASSWORD}` to `"pa"` in both paths, and `PASSWORD=pa$$!DUMMY_TOKEN`and`VALUE=${DUMMY_TOKEN}` (`DUMMY_TOKEN="$!SAMPLE_SECRET_DO_NOT_USE"`) stayed literal in both paths. For braced expressions with no `$`in the key,`${APP.VERSION}`and`${1}` looked up those literal keys.
3206
+ - **Seed counts.** Over the original 2,500 default seeds of `dotenv-equivalence.spec.ts` (468 skipped as non-terminating), the former follower passed 878 with 0 mismatches, the cycle-rejecting static check passed 567 (311 narrowed, 0 mismatches), and the cycle-allowing static check passed 597 and refused 1,435 with 0 mismatches. Over the updated 2,500-seed suite (where references written in the generated files follow a strict acyclic order plus leaf `RUSTFLAGS` self-append cases, while references that only come into being by substitution — through variable-name literals, explicit `$$HOST`/`$$CMD` indirection, dynamic `${...}` assembly or adjacent text joining — are not restricted by that order; all 2,500 default seeds terminate in Nx's loader with no second simulator, alongside fixed cases for terminating multi-variable cycles, `split(null)`, earlier-escaped `replace` targets, unclosed `${`, `${}`, `\\$FORCE_COLOR`, and `${SET:?error}`), 716 passed, 1,784 were refused, 0 were skipped, and 0 mismatched.
3207
+ :::
3208
+
3209
+ :::mara evidence EVD-NX-24-ULTRACACHE
3210
+ :mid: 01M81ARX6H8G4E0GJX0GX03D7K
3211
+ :title: What Nx 24.0.6 Ultracache replaces in a task's hash plan and tracks at run time
3212
+ :status: accepted
3213
+ :supports: DES-INPUTS
3214
+ :supports: RISK-UNDECLARED-INPUTS
3215
+
3216
+ A reading of `nx` 24.0.6 (`dist/src/ultracache/`, `dist/src/tasks-runner/task-io-service.js`, `dist/src/tasks-runner/forked-process-task-runner.js`, `dist/src/hasher/hash-task.js`, `dist/src/native/index.d.ts`) and direct probes of its native `HashPlanner`, `UltracacheConfigurationStore` and `getUltracacheReport` on 22 November 2026 on Linux x86-64 with Node 26.13.1 (nxr-j25xwy).
3217
+
3218
+ - **What `mode: "on"` (the default) keeps vs. replaces.** Importing an Ultracache recording (`{ commit, inputs: ["crates/app/src/main.rs"], outputs: ["target/debug/app", "target/debug/deps/app.o"] }`) into `UltracacheConfigurationStore` and calling `HashPlanner.getPlans` for a target with `{ fileset: "{projectRoot}/**/*" }`, `{ fileset: "{workspaceRoot}/Cargo.lock", always: true }`, `{ fileset: "{workspaceRoot}/rust-toolchain.toml" }`, `{ env: "RUSTFLAGS" }`, `{ runtime: "rustc -Vv" }`, `{ externalDependencies: ["nx"] }` and `"^default"` showed:
3219
+ - Kept unchanged: `runtime:rustc -Vv`, `env:RUSTFLAGS`, `env:NX_CLOUD_ENCRYPTION_KEY`, `npm:nx`, `ProjectConfiguration`, `nx.json`/`.gitignore`/`.nxignore`, and `{workspaceRoot}/Cargo.lock` (because it set `always: true`).
3220
+ - Dropped and replaced: `{projectRoot}/**/*`, `^default` (`lib:crates/lib/**/*`) and `{workspaceRoot}/rust-toolchain.toml` (without `always: true`) were dropped and replaced by `files:[crates/app/src/main.rs]` and `io-snapshot:<hash>`.
3221
+ - `UltracacheMode.On` documents that the recording stands in for the target's declared inputs and outputs; `TaskUltracacheSettings.collectStats` defaults to `false`.
3222
+ - **What `mode: "warn"` and `mode: "off"` do.** In `HashPlanner.getPlans`, both `mode: "warn"` (`getUltracacheReport` diagnostic `autofix-disabled`) and `mode: "off"` (`disabled`) kept every declared input intact. At run time, `registerTaskProcessStart` (`task-io-service.js`) notifies `TaskIOService` of the task's PID unless `task.ultracache?.mode === "off"` (so `warn` still traces IO and reports undeclared reads/writes, including Cargo's intermediate writes inside `target/` and sibling reads under `workspace-build`, while `off` suppresses tracing altogether).
3223
+ - **Batched vs. single tasks.** `forkProcessForBatch` (`forked-process-task-runner.js`) registers the batch worker with `ProcessMetricsService` only and does not call `registerTaskProcessStart`; only single-task runs (`nx run`, `--batch=false`, `NX_BATCH_MODE=false`) register their PID with `TaskIOService`.
3224
+ - **Consequence for Rust targets.** Leaving `ultracache.mode` at `"on"` risks stale cache hits whenever an unbatched Rust task is recorded on a warm Cargo build (where unchanged files are only `stat`'d while `collectStats` is `false`), under `NX_RUST_TEST_MODE=affected`, or across platform/feature `#[cfg(...)]` branches, and conflicts with [[ADR-RESULTS-ONLY-CACHE]] because Cargo writes intermediate files to `target/` outside declared outputs. Setting `ultracache: { mode: "off" }` keeps declared inputs and outputs authoritative and avoids noisy warnings and tracing overhead on `cargo`/`rustc` process trees.
3225
+
3226
+ Not run: a live Nx Cloud workspace with a recording worker; only Nx 24.0.6's local native `HashPlanner`, `UltracacheConfigurationStore` and JavaScript task-runner sources were exercised.
3227
+ :::
3228
+
3229
+ :::mara evidence EVD-CLIPPY-RUSTFMT-CONFIG-LOOKUP
3230
+ :mid: 01M81GZP7WVSAEGZMZ8469VS80
3231
+ :title: Which configuration file clippy takes under CLIPPY_CONF_DIR, also from Cargo's [env], and rustfmt takes outside the repository
3232
+ :status: accepted
3233
+ :supports: DES-INPUTS
3234
+ :supports: DES-DIAGNOSTICS
3235
+ :supports: RISK-HOST-ENVIRONMENT
3236
+
3237
+ Experiments on 22 November 2026 on Linux with clippy 0.1.100 and rustfmt 1.11.0 (toolchain 1.100.0) and with clippy 0.1.91 and rustfmt 1.8.0 (toolchain 1.91.0), which agreed in every case, in a throwaway virtual workspace `ws` with one member `a` whose `pub fn f(a: u8, b: u8, c: u8)` clippy reports where `too-many-arguments-threshold` is below 3, and whose `let` line rustfmt indents by `tab_spaces` (nxr-rpcfg4).
3238
+
3239
+ - **Clippy with `CLIPPY_CONF_DIR`.** With the variable naming a folder that holds `clippy.toml` with the threshold 2, `cargo clippy` reported the function; the crate's own `clippy.toml` with the threshold 5 was ignored. A folder that holds both `.clippy.toml` and `clippy.toml` gave `.clippy.toml`, with the warning "using config file `…/.clippy.toml`, `…/clippy.toml` will be ignored". A folder that holds neither, below one that holds `clippy.toml`, gave the parent's file: clippy looks from the named folder up to the file system's root and takes the first folder that holds either name. A folder named `clippy.toml` counts as no file. A symbolic link to the folder worked as the folder.
3240
+ - **Relative and missing folders.** A relative value is resolved against the workspace root, where cargo runs clippy-driver: `../conf` worked from the workspace root and from the member's folder alike, and `../../conf` from the member's folder failed. A missing folder or an empty value fails the crate's compilation, with "failed to read `CLIPPY_CONF_DIR` as a directory" in 1.100 and "error finding Clippy's configuration file" in 1.91. An unreadable `clippy.toml`, and one that is no valid TOML, fail it as well.
3241
+ - **`CLIPPY_CONF_DIR` from Cargo's `[env]`.** In a workspace `above/ws` whose member denies `clippy::too_many_arguments`, with `ws/conf/clippy.toml` at the threshold 2 and `above/conf/clippy.toml` at 5, and the variable unset in the shell: `CLIPPY_CONF_DIR = "conf"` in `ws/.cargo/config.toml` gave `ws/conf`, also with cargo started in the member's folder, and the same string in `above/.cargo/config.toml` gave `ws/conf` too, so a value without `relative` reaches clippy-driver as written and is resolved from the workspace root. A table `{ value = "conf" }` and `{ value = "conf", relative = false }` did the same. `{ value = "conf", relative = true }` gave `above/conf` in `above/.cargo/config.toml` and `ws/conf` in `ws/.cargo/config.toml`: the folder that holds the `.cargo` folder of the file. With both files setting it, the deeper file's value counted. With the variable set in the shell to `above/conf`, a file without `force` left the shell's value, and `force = true`, with or without `relative`, replaced it. An absolute string named its folder as it is.
3242
+ - **Rustfmt and a source file outside the crate's folder.** rustfmt looks for its configuration from the folder of each file it formats: with `[lib] path` naming a file in another folder of the repository, beside no configuration file, and a `rustfmt.toml` in the crate's own folder, rustfmt formatted that file with the per-user configuration, which the unit test of nxr-rpcfg4 runs with the real rustfmt. Where reading a folder fails with an error other than a missing file, such as a folder that cannot be searched, rustfmt fails instead of looking further; a path through something that is no folder counts as missing in 1.100 and as an error in 1.91, read in `src/tools/rustfmt/src/config/mod.rs` of both tags and not run.
3243
+ - **Rustfmt outside the repository.** With a repository below a folder `above`, `HOME` set to a folder `home` and `XDG_CONFIG_HOME` to a folder `xdg`, `cargo fmt -- --emit stdout` took, where no folder from the crate's up to the repository root held a configuration file: a `rustfmt.toml` in `above`, before any per-user file; then `home/.rustfmt.toml`, then `home/rustfmt.toml`; then `xdg/rustfmt/.rustfmt.toml`, then `xdg/rustfmt/rustfmt.toml`. With `XDG_CONFIG_HOME` unset, empty or relative, it took `home/.config/rustfmt/rustfmt.toml` instead. A `rustfmt.toml` at the repository root replaced every one of them, without merging. Where the home folder is itself above the repository, its file is found in the walk up.
3244
+
3245
+ Not run: macOS, where the `dirs` crate that rustfmt uses names `Library/Application Support` in the home folder as the configuration folder, and an empty `HOME`, which that crate takes as unset.
3246
+ :::
3247
+
3248
+ ## Sources
3249
+
3250
+ Pages and repositories read for the design discussion, on 12 November 2026.
3251
+
3252
+ - [eddacraft/nxrust](https://github.com/eddacraft/nxrust): `docs/product-spec.md`, the cache design document, `src/graph.ts`, `src/utils/cache-inputs.ts`, `plans/issues.md`, `plans/modules/10-wasm-napi.aps.md`
3253
+ - [max-sixty/cargo-affected](https://github.com/max-sixty/cargo-affected): README, `docs/report-json.md`, architecture notes
3254
+ - [nrwl/nx](https://github.com/nrwl/nx) source at main: `misc-interfaces.ts`, `tasks-schedule.ts`, `tasks-runner/utils.ts`
3255
+ - [Nx: Add Language Support to Nx](https://nx.dev/docs/kb/add-language-support.md)
3256
+ - [Nx 23.3 release post](https://nx.dev/blog/nx-23-3-release): task-based affected, batched oxlint executor
3257
+ - [Nx batch parallelism repro](https://github.com/ineentho/nx-batch-parallelism-repro)
3258
+ - [@monodon/rust 3.0.0 release](https://github.com/Cammisuli/monodon/releases/tag/rust-3.0.0)
3259
+ - [Cargo build cache reference](https://doc.rust-lang.org/beta/cargo/reference/build-cache.html): build-dir and target-dir
3260
+ - [Call for Testing: Build Dir Layout v2](https://blog.rust-lang.org/2026/03/13/call-for-testing-build-dir-layout-v2)
3261
+ - [Rework Cargo Build Dir Layout](https://goals.rust-lang.org/2025h2/cargo-build-dir-layout.html): build cache locking
3262
+ - [Cargo unstable features](https://doc.rust-lang.org/cargo/reference/unstable.html): feature-unification
3263
+ - [cargo-hakari: about workspace-hack crates](https://docs.rs/cargo-hakari/latest/cargo_hakari/about/index.html)
3264
+ - [nextest filterset reference](https://nexte.st/docs/filtersets/reference/)
3265
+ - [nextest: archiving and reusing builds](https://nexte.st/docs/ci-features/archiving/)
3266
+ - [Sunsetting the rustwasm GitHub org](https://blog.rust-lang.org/inside-rust/2025/07/21/sunsetting-the-rustwasm-github-org)
3267
+ - [napi-rs: cross build](https://napi.rs/docs/cross-build)