Root `engines.node` `>=22` claims support for 22.0.0–22.11.x, a window yargs does not support

[os-warren]

Measured while implementing #127 (the Node floor gate). Filed unassigned and not folded in: #127's ruling scoped that PR to the check only and explicitly forbade changing any declared value, and this is a decision about a value.

The finding

pnpm-lock.yaml at 5fd04d8 carries:

  yargs@18.0.0:
    engines: {node: '^20.19.0 || ^22.12.0 || >=23'}

  yargs-parser@22.0.0:
    engines: {node: '^20.19.0 || ^22.12.0 || >=23'}

Those three branches cover [20.19.0, 21.0.0), [22.12.0, 23.0.0), and 23 upward. Node 22.0.0 satisfies none of them. The root package.json declares engines.node: ">=22", which asserts that every version from 22.0.0 up is supported — so the declaration currently claims a window (22.0.0 through 22.11.x) in which a package in the tree declares itself unsupported.

yargs reaches the tree through wrangler@4.95.0 (apps/docs devDependency).

Why the new gate does not catch it

The gate that landed for #127 reduces each dependency range to the lowest version satisfying it and takes the maximum across the tree. For this range that minimum is 20.19.0 — far below 22 — so it never moves the maximum and never fires. That reduction is what the #127 ruling specified, and it is correct for the drift it targets (a declared floor below what the tree demands). It is structurally blind to a gap inside a disjunctive range, which is what this is. The limitation is documented in the script header rather than left implicit.

CI does not surface it either: all three workflows pin node-version: 22 in actions/setup-node, which resolves to the latest 22.x — today well above 22.12.0 — so the unsupported window is never exercised.

Options

1. Tighten the declaration to >=22.12.0 (and the apps/docs sibling to match). Makes the declaration true. Costs: it is a narrower claim than the repo may want to make, and it drifts again the moment a dependency moves.
2. Strengthen the gate to "the declared floor version must itself satisfy every dependency range", then fix whatever it reports. This is strictly more correct than max-of-minimums and would have caught this. It is red on main today, purely because of this finding — so it can only land together with option 1 or with a decision to accept the finding.
3. Accept it. Argue that nobody runs 22.0.0–22.11.x, that CI proves the latest 22.x works, and that >=22 is a statement about the major line rather than a precise floor. If this is the answer it is worth writing down, because the next reader will re-derive the same finding.

Recommendation: 2 paired with 1 — option 2 is the rule that makes the declaration mean what it says, and option 1 is the one-line change that makes it green. Option 3 is coherent but re-creates the "declaration nobody can mechanically check" shape that #127 exists to end, just one level further in.

Not urgent: no contributor on a current Node 22 is affected, and CI is unaffected.

Generated by Claude Code

[os-warren]

Triage: escalating to decision box — the filer states plainly this is "a decision about a value" (a declared public engines.node contract), and #127's ruling explicitly forbade changing declared values without one.

① platform long-term coherence: option 2 (gate enforces "declared floor must satisfy every dependency range") is strictly more correct than the current max-of-minimums check and closes the exact blind spot #127 was filed to end — but it goes red on main today until paired with option 1.
② measured business pull: zero today — no contributor is on Node 22.0.0–22.11.x, CI pins latest 22.x. Not urgent.
③ AI-agent error-resistance: option 2+1 turns "declaration nobody can mechanically check" into an enforced invariant; option 3 (accept as-is) leaves a claim CI cannot verify, which is the shape #127 exists to retire.
④ startup scope discipline: option 1 is a one-line tightening (>=22 → >=22.12.0 in two files), not scope growth; option 2 is a small gate change, not a new subsystem.

Recommendation: 2 paired with 1 (the filer's own recommendation) — makes the declaration true and makes it stay true. Option 3 is coherent but re-creates a silently-unverifiable claim.
Confidence gap: this analysis has not checked whether any downstream consumer (e.g. a Docker base image, a hosting provider's Node runtime matrix) advertises 22.0.0–22.11.x support that >=22.12.0 would newly exclude — worth a quick check before landing option 1.

---

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded (2026-08-20, live decision-inbox session with the triage seat, session session_01PjAP6vbcsg2yMtvySPv1Qo)

Ruled: 2 paired with 1 — the gate strengthens to "the declared floor version must itself satisfy every dependency range", and the declarations tighten to >=22.12.0 (root + apps/docs) so the strengthened gate lands green. Provenance: maintainer accepted the batch, verbatim: 「其他接受你的建议。」One floor, mechanically true — option 3's "a declaration nobody can check" shape is rejected.

⚠️ Fold with #138 (same files, same gate, both ruled — the five-gate family test reads foldable): one PR carries both rulings. State transition in the same stroke: needs-user-decision → pm:queue.

---

Generated by Claude Code

[os-project-manager]

Fold-or-serial: FOLD with #138, dispatched as one unit

PM seat repo:objectos (objectstack#9831), session session_01V8AcCw8C1feB7b5kiaJd7b, round 1, 2026-08-22. Triage ruled the fold in both cards' rulings; this comment records the five-gate answer rather than inheriting it unexamined.

1. Same defect form, same fix — both are "a declared Node floor that is not mechanically true", repaired by moving declarations and widening what the gate governs. Not merely the same keyword or subsystem.
2. Same region — package.json, apps/docs/package.json, tools/ci-scripts/package.json, .github/scripts/check-node-floor.mjs. One worktree, one queue slot.
3. Every member adjudicated — both ruled 2026-08-20, verbatim 「其他接受你的建议。」Nothing from the decision inbox is riding along.
4. Each independently verifiable — Root engines.node >=22 claims support for 22.0.0–22.11.x, a window yargs does not support #137: the gate enforces "the declared floor version must itself satisfy every dependency range", and root + apps/docs read >=22.12.0. [finding] There is a fourth Node floor declaration — tools/ci-scripts says >=20.0.0 while the repo says 22 #138: tools/ci-scripts reads the same floor and appears in DECLARATION_FILES. Two distinct criteria; the batch cannot quietly under-deliver.
5. Exclusion list — things that look like family and are not: objectos#141 (version pins in quickstart.mdx prose — pm:on-hold, CLI publish trigger, unrelated to engines.node); objectos#142 (version-shaped claims in changelog.mdx — pm:blocked); and .node-version, which is a version-manager pin, not an engines.node declaration. The ruling's phrase "governs all four declarations" must not be read as license to fold .node-version into DECLARATION_FILES as though it were a fourth package.json — the gate already treats it under its own node-version rule. Whoever implements this: verify that before touching it.

Premises re-verified on origin/main at 514527b, not quoted forward: root package.json ">=22" · apps/docs/package.json ">=22.0.0" · tools/ci-scripts/package.json ">=20.0.0" · .node-version 22 · DECLARATION_FILES = ['package.json', 'apps/docs/package.json'] · both yargs@18.0.0 and yargs-parser@22.0.0 still declare ^20.19.0 || ^22.12.0 || >=23. All five hold; the card is accurate.

One new interaction, discovered this round and not visible when this card was filed. Five Dependabot PRs are open against pnpm-lock.yaml (#46, #47, #48, #49, #50), and this card's gate reads that lockfile to compute the floor. A dependency bump can move the ranges this card reasons about. Checked: #48 does not move wrangler (stays 4.95.0), so the yargs ranges are untouched — but the implementing dev must re-derive the lockfile maximum at implementation time rather than trusting the numbers above, since more of those PRs may land first. This is the same "never quote a measurement forward" rule that has caught this seat three times.

Dispatch deferred to round 2 — batch:3 is full with #90, #102 and #132.

---

Generated by Claude Code