build(toolchain): reconcile Node engine floor with jsdom 30 requirements

[qnbs]

Context

Dependabot PR #754 upgraded jsdom from 29.1.1 to 30.0.1 and has since been merged into main.

Current repository truth now contains a concrete toolchain-support mismatch:

package.json
  engines.node = ">=22.19.0"

README.md
  Node.js ≥ 22.19.0

.nvmrc
  22

jsdom 30.0.1
  engines.node = "^22.22.2 || ^24.15.0 || >=26.0.0"

Upstream jsdom 30 deliberately raised its Node minimum/support range to:

^22.22.2 || ^24.15.0 || >=26.0.0

Therefore WorldScript currently advertises Node versions as supported that a direct dev dependency no longer supports. In particular:

• Node 22.19.0 through 22.22.1 satisfy WorldScript's declared >=22.19.0 contract but do not satisfy jsdom 30;
• a broad >=22.19.0 range also admits Node 24 releases below 24.15.0 even though jsdom 30 does not;
• ordinary CI jobs using major lanes such as Node 22/24 resolve to current patch releases, so green CI does not prove the declared minimum-version contract.

This is a developer/build-toolchain truth defect, not evidence of a production runtime failure.

Goal

Make the repository's Node support promise internally consistent with the actual dependency graph and test toolchain.

Choose and document one intentional contract rather than leaving the current accidental mismatch.

Required decision

Option A — raise/narrow the supported Node range

If jsdom 30 is retained, align WorldScript's declared Node support with the real binding dependency requirement.

Do not mechanically change the floor to only >=22.22.2, because that would still admit unsupported Node 24.0–24.14 releases.

Derive an explicit range compatible with both repository policy and jsdom, for example conceptually:

^22.22.2 || ^24.15.0

if WorldScript intentionally supports only the currently tested 22/24 families, or a broader range only if newer majors are deliberately admitted and tested.

Option B — retain the existing WorldScript Node floor

If Node >=22.19.0 compatibility is intentional and important, revert/pin the test DOM dependency to a version whose engine contract actually includes that floor rather than falsely claiming support while keeping jsdom 30.

Do not choose between these options solely to silence an engine warning.

Surfaces to reconcile

At minimum inspect and synchronize, where applicable:

• package.json engines.node;
• .nvmrc;
• README.md Requirements;
• CONTRIBUTING.md / developer setup docs;
• .github/actions/setup/action.yml and workflow Node lanes;
• low-end CI/Act helpers that derive or describe Node support;
• any toolchain doctor/check script that validates the Node floor;
• lockfile/dependency-state behavior.

Do not rewrite historical audit documents merely because they mention an older floor unless they are incorrectly presented as current authority.

Add a deterministic drift guard

The current failure class can recur whenever a direct/dev dependency raises its Node engine range while CI continues using only the latest patch of a major line.

Evaluate the smallest deterministic guard that can fail when the repository claims a Node version unsupported by binding direct tooling dependencies.

Possible approaches include:

• an explicit authoritative minimum/range checked by the existing toolchain script;
• a focused dependency-engine consistency check over direct dependencies that participate in required development/test workflows;
• a CI lane exercising the actual declared minimum patch where practical.

Avoid building a general dependency-policy framework solely for this issue.

The invariant should be:

version advertised as supported by WorldScript
→ required install/test toolchain must support that version

A major-only CI lane resolving to the newest patch is not sufficient evidence for that invariant.

Relationship to #749

#749 is the separate Vitest 5 / Playwright dev-tooling update with its own known migration failure. Do not fold this Node/jsdom support-contract correction into #749 merely because both concern dev tooling.

If #749 or a later dependency update introduces a stricter Node requirement, re-derive the final range from the then-current dependency graph before implementing this issue.

Acceptance criteria

• Current jsdom/other binding direct-tool engine requirements are re-fetched from the installed/current dependency versions.
• WorldScript's intentional Node support policy is explicitly chosen.
• package.json no longer advertises Node versions unsupported by the required dev/test dependency graph.
• README and current developer setup documentation match the package/toolchain contract.
• .nvmrc, CI setup and low-end tooling are reconciled with the chosen policy rather than left semantically ambiguous.
• A deterministic regression guard or minimum-version qualification prevents the same silent drift class from recurring where practical.
• Current Node 22 and Node 24 CI lanes remain green under the chosen contract.
• No production/runtime behavior is changed merely to solve a dev-tool support mismatch.
• build(deps-dev): bump the dev-tooling group across 1 directory with 3 updates #749 remains independently scoped.
• Exact-head CI/review convergence and resulting-main verification complete before closure.

Priority

P2 developer/toolchain correctness.

The current main build is not known to be broken because hosted CI resolves supported current patch releases, but the repository's documented minimum/support range is presently broader than the direct test dependency actually supports. Correct before the next release/developer-setup truth pass so contributors are not told that an unsupported Node version is valid.

[qnbs]

Current-main addendum — jsdom 30 is also being forced onto an unsupported undici major — 2026-09-16

Revalidated against main 4137286887275ca03aa5b75906e6b529c68c786c.

The Node-floor mismatch in this issue is not the only post-#754 dependency-contract drift. pnpm-workspace.yaml still contains:

overrides:
  undici: ">=7.29.0 <8"

That cap was introduced for the previous dependency graph. The current jsdom@30.0.1 line declares undici ^8.9.0, while the repository-wide override forces the resolved graph back onto undici 7.x. The 2026-09-16 audit verified the resulting lockfile resolution as undici 7.29.0 beneath jsdom 30.

Current CI happens to be green and the audited jsdom 30 call surface appeared to use exports still present in 7.x, so this is not evidence of an active runtime failure. It is, however, an unsupported dependency combination and should be resolved deliberately rather than normalized as green-CI evidence.

Fold into this issue's A/B decision

When deciding whether to keep jsdom 30 or restore the previous toolchain compatibility contract, also classify the undici override:

• recover the original reason/owner for >=7.29.0 <8;
• verify whether any current direct/transitive consumer still requires the <8 cap;
• if obsolete, remove/narrow it and allow jsdom 30 to resolve its supported undici line;
• if still required by another consumer, do not force jsdom 30 through an unsupported major — choose a compatible dependency graph instead;
• fresh-resolve and frozen-reinstall the selected graph, then run the relevant Node 22/24 unit/jsdom/browser tooling evidence.

Add an explicit regression invariant:

repository override policy must not force a direct binding dependency outside its declared supported semver range without a documented, tested compatibility exception and removal condition

This remains separate from #749's Vitest 5 migration and from #571's Playwright skew, but all three should be considered when declaring the final supported Node/toolchain matrix.

[qnbs]

2026-09-20 toolchain update — Vitest 5 success does not resolve the Node/jsdom/undici contract

PR #782 is now the active clean-base Vitest 5 migration after #749 was closed unmerged.

On #782 head 0f045f2a28241c27d405388d5986148184126599, the Node 24 Quality Gate completed successfully, including typecheck, the full ordinary Vitest suite and coverage ratchet; Node 22 was also progressing through the full lane.

That is useful compatibility evidence, but it does not close this issue:

• hosted Node 22/24 lanes resolve current patch releases, not the repository's advertised minimum patches;
• green Vitest 5/jsdom execution does not make >=22.19.0 truthful if binding dependencies exclude portions of that range;
• it also does not prove the repository-wide undici <8 override is a supported graph for jsdom 30.

After #782 settles, re-derive #762 from the final installed graph. Keep the decision causal: Node/jsdom/undici support truth belongs here, not in the Vitest migration.