|
| 1 | +# OpenDesign Node.js Output Checks 2026-10 |
| 2 | + |
| 3 | +## Context |
| 4 | + |
| 5 | +`abird-host-manager fleet build` failed on `pvl-x2` while building the |
| 6 | +OpenDesign container image: |
| 7 | + |
| 8 | +```text |
| 9 | +error: derivation '/nix/store/wgipqnr5aqcfbxh0jwvb0q1zhdjj54gn-nodejs-slim-24.18.0.drv' |
| 10 | + output check for 'libv8' contains output name 'out', but this is not a |
| 11 | + valid output of this derivation. |
| 12 | + (Valid outputs are [corepack, dev, libv8, npm].) |
| 13 | +``` |
| 14 | + |
| 15 | +The failure was deterministic across repeated `fleet build` runs and blocked the |
| 16 | +whole fleet (every host builds through `pvl-x2`). |
| 17 | + |
| 18 | +## Root cause |
| 19 | + |
| 20 | +Two facts combine: |
| 21 | + |
| 22 | +1. `nixpkgs` `nodejs-slim` uses `__structuredAttrs = true` with cross-output |
| 23 | + `outputChecks`, for example |
| 24 | + `libv8.disallowedReferences = [ "out" "npm" ... ]`. |
| 25 | +2. Nix 2.34 resolves those symbolic output names against only the outputs it |
| 26 | + realizes in the current build (`infos`), not against all derivation outputs. |
| 27 | + In `src/libstore/build/derivation-check.cc`, `checkRefs` looks up `outputs` |
| 28 | + (built this run) and throws when a referenced output name is absent. |
| 29 | + |
| 30 | +When the builder store holds a partial output set, Nix skips the already-valid |
| 31 | +outputs and rebuilds only the missing ones. The check then fails because the |
| 32 | +already-valid output is not in the current-run set. |
| 33 | + |
| 34 | +On `pvl-x2` the pinned, out-of-cache `nodejs-slim-24.18.0` had only `out` valid: |
| 35 | + |
| 36 | +```text |
| 37 | +yyvsyz78...-nodejs-slim-24.18.0 VALID (ultimate, signed pvl-1) |
| 38 | +crwbzp1r...-nodejs-slim-24.18.0-corepack missing |
| 39 | +cn19s1vs...-nodejs-slim-24.18.0-dev missing |
| 40 | +33r9mrvr...-nodejs-slim-24.18.0-libv8 missing |
| 41 | +rm6i1kz6...-nodejs-slim-24.18.0-npm missing |
| 42 | +``` |
| 43 | + |
| 44 | +The partial set comes from the builder store's GC/retention: the lone `out` |
| 45 | +survived while the other outputs were collected. Because `pvl-x2` builds |
| 46 | +`nodejs-slim` (all outputs are produced whenever the derivation is realized), |
| 47 | +every retry hit the same `libv8` check against the still-valid `out`. |
| 48 | + |
| 49 | +Minimal reproduction (any Nix 2.34 host): |
| 50 | + |
| 51 | +```nix |
| 52 | +pkgs.stdenv.mkDerivation { |
| 53 | + pname = "outcheck-demo"; |
| 54 | + version = "1"; |
| 55 | + __structuredAttrs = true; |
| 56 | + outputs = ["out" "extra"]; |
| 57 | + outputChecks.extra.disallowedReferences = ["out"]; |
| 58 | + dontUnpack = true; |
| 59 | + buildCommand = "mkdir -p $out $extra; echo x > $out/m; echo y > $extra/m"; |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +Build it, delete only `extra`, then build `^extra` while `out` is still valid: |
| 64 | + |
| 65 | +```text |
| 66 | +error: ... output check for 'extra' contains output name 'out', but this is not |
| 67 | + a valid output of this derivation. (Valid outputs are [extra].) |
| 68 | +``` |
| 69 | + |
| 70 | +This is a Nix limitation, not a Nixpkgs or OpenDesign derivation bug. The same |
| 71 | +shape can affect any multi-output derivation with cross-output `outputChecks` |
| 72 | +when the builder holds a strict partial output set. |
| 73 | + |
| 74 | +## Custom Node pin still required (2026-10-04) |
| 75 | + |
| 76 | +The OpenDesign runtime still needs the pinned Node 24.18.0. The pin exists for |
| 77 | +the `node::ObjectWrap` cleanup-hook regression, and that regression is unfixed |
| 78 | +in the newest Node 24.x available through nixpkgs: |
| 79 | + |
| 80 | +- Regression introduced by `nodejs/node#63642` |
| 81 | + (`src: add cleanup hooks to |
| 82 | + node::ObjectWrap`, commit `4b5eb7b72d`), first |
| 83 | + shipped in **24.19.0** (2026-08-03). `~ObjectWrap()` now calls |
| 84 | + `RemoveEnvironmentCleanupHook()` during GC, when no `Environment` is |
| 85 | + associated with the isolate, and aborts with |
| 86 | + `Assertion failed: (env) != nullptr`. |
| 87 | +- Upstream issue `nodejs/node#65446` is still open (created 2026-08-20). The |
| 88 | + v24.x backport of the fix, `nodejs/node#65943`, is closed unmerged; the fix |
| 89 | + PRs are `nodejs/node#63985` and `nodejs/node#65630`. |
| 90 | +- `nixpkgs` stable and unstable both ship **24.21.0** (2026-09-08), and there is |
| 91 | + no newer 24.x release. `src/node_object_wrap.h` at tag `v24.21.0` still calls |
| 92 | + the unguarded |
| 93 | + `RemoveEnvironmentCleanupHook(v8::Isolate::GetCurrent(), |
| 94 | + ...)`. |
| 95 | +- OpenDesign 0.23.0 uses `[email protected]`, which subclasses |
| 96 | + `node::ObjectWrap` (`Statement`, `Database`, `Backup`, `StatementIterator`) |
| 97 | + and is rebuilt from source against the pinned headers. Per |
| 98 | + `nodejs/node#65446`, the crash follows the headers an addon is compiled |
| 99 | + against, so shipping a 24.19.0-or-later runtime with matching headers |
| 100 | + re-introduces the abort. |
| 101 | + |
| 102 | +Dropping the pin therefore re-introduces the crash. The OpenSSL CCM patch is |
| 103 | +only needed because the runtime is pinned to 24.18.0; commit `1433cf9d` |
| 104 | +(`nodejs/node#65542`) is already in 24.21.0. When upstream lands the |
| 105 | +`ObjectWrap` fix in a 24.x release and nixpkgs adopts it, both the pin and the |
| 106 | +CCM patch can be dropped, and this `outputChecks = {}` workaround becomes |
| 107 | +unnecessary (stock `nodejs-slim` is fully cacheable and is not partially built |
| 108 | +in practice). |
| 109 | + |
| 110 | +## Decision |
| 111 | + |
| 112 | +Disable the cross-output reference checks on the OpenDesign-pinned Node.js |
| 113 | +runtime only, in `pkgs/ext/opendesign/default.nix`: |
| 114 | + |
| 115 | +```nix |
| 116 | +outputChecks = {}; |
| 117 | +``` |
| 118 | + |
| 119 | +Rationale: |
| 120 | + |
| 121 | +- The pin is out-of-cache and local to this image, so it is the derivation most |
| 122 | + exposed to partial builder-store state. |
| 123 | +- Disabling `outputChecks` changes the derivation hash, so the poisoned `out` |
| 124 | + never matches again and all outputs build and register together. |
| 125 | +- It also makes future partial store state harmless: an empty `outputChecks` |
| 126 | + never resolves symbolic output names, so rebuilding missing outputs succeeds. |
| 127 | +- The build script is untouched, so output contents are identical; only store |
| 128 | + paths change. |
| 129 | + |
| 130 | +Tradeoff: this drops nixpkgs' output-reference discipline checks for this |
| 131 | +runtime. Those checks only validate the unchanged upstream build script; they do |
| 132 | +not change what is built. Prefer a real Nix fix if one lands. |
| 133 | + |
| 134 | +## Alternatives considered |
| 135 | + |
| 136 | +- Repair the builder store only (delete the stale `out`, or rebuild all |
| 137 | + outputs), no code change. Fixes the immediate failure but recurs after the |
| 138 | + next GC that retains a subset of outputs. |
| 139 | +- Patch Nix `checkRefs` to resolve output names against `drv.outputs` rather |
| 140 | + than only the current run. This is the general fix, but it requires |
| 141 | + bootstrapping a patched Nix onto `pvl-x2` and maintaining an upstream patch. |
| 142 | +- Enable `keep-outputs` on the builder. Keeps all outputs but is global and |
| 143 | + increases builder disk use. |
| 144 | + |
| 145 | +## Validation |
| 146 | + |
| 147 | +- Minimal Nix 2.34 reproduction fails with `outputChecks`, and the same |
| 148 | + derivation with `outputChecks = {}` rebuilds a deleted output while `out` |
| 149 | + stays valid. |
| 150 | +- The OpenDesign image re-evaluates to a new derivation with neutralized checks: |
| 151 | + - old `nodejs-slim` drv: |
| 152 | + `wgipqnr5aqcfbxh0jwvb0q1zhdjj54gn-nodejs-slim-24.18.0.drv` |
| 153 | + - new `nodejs-slim` drv: |
| 154 | + `0g9pk6c8bdiv1yq6amd1ribhyn7clq8s-nodejs-slim-24.18.0.drv` |
| 155 | + - new `structuredAttrs.outputChecks`: all empty (`{corepack={};dev={};...}`) |
| 156 | + |
| 157 | +## Follow-ups |
| 158 | + |
| 159 | +- Re-run `nix run .#abird-host-manager -- fleet build`; all `nodejs-slim` |
| 160 | + outputs build fresh under the new derivation hash. |
| 161 | +- If this shape appears for another out-of-cache multi-output package, prefer |
| 162 | + the Nix `checkRefs` patch over per-package `outputChecks = {}`. |
0 commit comments