Workflow node-version pins can drift from engines.node without detection

[lamemustafa]

Split out of #331, where four review rounds showed the check cannot be done correctly by regex.

What is unguarded

Every workflow pins node-version: 24.20.0 and package.json declares engines.node: ">=24.20.0". Nothing enforces that they agree. A workflow could pin a different major, pin a version below the declared minimum, or lose its pin entirely and fall back to the runner default, and no check would notice.

Why #331 stopped trying

tests/repo/node-runtime-types-alignment.test.ts attempted this by scanning the YAML with regexes. Review found four ways it passed while broken, each surfacing only after the previous was fixed:

1. Lexical version comparison — "24.9.0" >= "24.20.0" is true, and "26.10.0" >= "26.4.1" is false. Wrong in both directions.
2. An aggregate count across files stayed positive when one file lost its pin.
3. A per-file count stayed positive when one of release.yml's two setup-node steps lost its pin.
4. A commented-out pin — # node-version: 24.20.0 — satisfies every regex while GitHub ignores it.

Each fix was correct and produced the next hole. The pattern is not sloppiness: associating a pin with its step requires knowing which with: block belongs to which step, which is YAML semantics, and this repo has a record of what happens when it hand-rolls a parser for a grammar it does not own (#197, six rounds).

The guard now asserts only that the resolved @types/node major matches engines.node, read from the lockfile. That covers the risk the dependabot ignore rule exists for, and cannot be fooled by comments, ranges, or indentation.

What a real fix needs

A YAML parse, so each actions/setup-node step is checked for its own active with.node-version. That means a parser dependency, which is ask-first here, and the trade should be stated rather than assumed: one small YAML dependency against a class of drift nothing currently detects.

Worth noting the exposure is modest — all seven workflows carry correct pins today, and a wrong pin would likely surface as a CI failure rather than silently. The reason to fix it is that "likely" is doing real work in that sentence.

Not blocking

Recorded so the gap is known rather than forgotten. #331 is deliberately narrower than the problem.

[lamemustafa]

Addressed in #364, by rejecting the approach this issue proposed rather than implementing it.

The issue asks for a YAML parse so each actions/setup-node step can be checked for its own active with.node-version, and correctly flags the parser as an ask-first dependency. #364 asserts the outcome instead: scripts/assert-node-runtime.mjs checks that the Node actually executing satisfies engines.node and shares a major with the @types/node the lockfile resolves.

Every failure mode #331 found over four rounds is a way of misreading YAML — lexical comparison, an aggregate count, a per-file count, a commented-out pin. None survives not reading any YAML. No parser, no dependency, and no second grammar this repo does not own.

A floor alone would not have been enough, which is worth recording because it is the non-obvious half. A dropped or commented-out pin falls back to the runner default, which may be newer: Node 26 satisfies >=24.20.0, so a minimum check would pass while @types/node still described Node 24 — tsc approving calls that do not exist at execution, which is the exact risk the dependabot @types/node major-ignore rule exists to cover. The major check closes that direction.

One of this issue's stated cases is already stale. It cites release.yml's two setup-node steps as the third hole; release.yml has one today. The class it illustrates is not stale, which is why this was fixed rather than closed as outdated.

It found a live instance immediately, in a direction the issue does not mention. This machine's local Node is 24.18.0 against engines.node: ">=24.20.0", and nothing was catching it:

error: Node 24.18.0 is older than the declared minimum >=24.20.0.

So the drift this issue describes is not merely possible — it is present, locally, today. The check is wired into verify:local as well as all seven workflows for that reason.

What #364 does not cover, stated rather than implied, since it is narrower than what was asked for:

• a workflow that never runs Node cannot be checked by a Node process (all seven run it today);
• a pin that is wrong but still inside the declared range passes — engines.node is the contract, and this enforces the contract rather than a specific patch version;
• from a green run you cannot tell which workflow drifted, only that none did; the drifting workflow is the one that fails, which is where the failure is useful.

If those limits turn out to matter, the YAML-parser route stays available and this comment is the record of why it was not taken first. I would close this issue when #364 merges, with the local-toolchain upgrade tracked separately — that is a toolchain fix, not a code change.