Audit: Rsbuild 2.2.1 dev-server and HMR conformance

[ScriptedAlchemy]

Scope

Conformance audit of the Rsbuild 2.2.1 development server, HMR relay, MultiCompiler observation, and runtime generation capture at 12526a8b9d1c5d096dc16a9aee823606997edade.

Verdict

Public Rsbuild usage is conformant. One behavior is wrong: the Runtime App relay treats Rsbuild's private ok frame as a reload request even though the provider already emits the documented full-reload operation only for changed App compilations.

Five seams depend on behavior that Rsbuild/Rspack does not document:

• raw JSON HMR frame shape and ok/hash ordering;
• WebSocket token alphabet and length;
• one-to-one FIFO pairing of global before/after dev compile hooks under MultiCompiler skew;
• Stats child names matching environment keys and cross-root writeToDisk cohort timing;
• startDevServer() / provider-tail timing appearing to act as an initial-compile barrier.

Disposition

The conformance fix branch removes ok-driven reloads, allowlists the provider-emitted full-reload kind, accepts bounded string tokens with URL encoding, derives the HMR path from normalized environment configuration, fails FIFO violations loudly, explicitly names compilers, and documents that startup may return in compiling state.

The deeper protocol-channel, completed-cohort identity, and immutable per-environment output staging changes require focused follow-ups linked to this audit.

References

• Rsbuild Environment API: hot.send('full-reload')
• Rsbuild dev hooks
• Rspack Stats JSON
• Rsbuild parallel environments

[ScriptedAlchemy]

Status update on the dev-runtime follow-ups:

• Replace raw Rsbuild HMR frames with a provider-owned Runtime App reload channel #73 — landed via feat(dev): replace raw Rsbuild HMR frames with a provider-owned Runtime App reload channel (#73) #84 (squash aafcf83). Runtime App reloads now travel entirely over provider-owned surfaces: changed-App compile hook → session-owned subscription → proxy-hosted one-way reload channel with generation replay on every (re)connect. No Rsbuild frame is parsed anywhere; fix(dev): harden runtime relay against Rsbuild internals #76's inert-frame posture survives as regression fixtures proving legacy ok/hash/full-reload frames stay inert on the owned channel. Review added one hardening on top: the bootstrap shell now tracks applied vs. requested reload generations, so a reload announced while a refresh fetch is in flight is applied by a catch-up refresh instead of being swallowed, and a failed refresh no longer burns its generation (the connect-time replay retries it).
• Stage immutable per-environment outputs before assembling runtime cohorts #74 — PR fix(dev): stage immutable per-environment output checkpoints before assembling runtime cohorts (#74) #85 under review (immutable per-environment staging); re-gating over this merge next.
• Make completed MultiCompiler cohorts authoritative without FIFO hook identity #75 — PR fix(dev): #75 — completed MultiStats cohorts are the authoritative compile identity, no FIFO hook pairing #83 under review by its own reviewer.

[ScriptedAlchemy]

• Stage immutable per-environment outputs before assembling runtime cohorts #74 — landed via fix(dev): stage immutable per-environment output checkpoints before assembling runtime cohorts (#74) #85 (squash 76de3ad). Runtime cohorts are now assembled exclusively from immutable per-environment checkpoints staged in each compiler's own onAfterEnvironmentCompile (awaited inside that compiler's done tap), matched by exact Stats hash; capture never reads or writes the live writeToDisk roots, every admitted byte is digest-verified against its staged checkpoint, and fix(dev): harden runtime relay against Rsbuild internals #76's foreign-file defense moved to staging time via the per-environment known-assets chain. Review added two lifecycle hardenings on top: failed staged-directory removals are remembered, retried at drain, and reject close() (surfacing as a structured environment-checkpoints cleanup failure) instead of being swallowed; and close() now waits for in-flight staging copies to settle before reporting the store drained. Re-gated over feat(dev): replace raw Rsbuild HMR frames with a provider-owned Runtime App reload channel (#73) #84's merge (clean composition: the reload channel and staging hooks share rsbuild.config.ts/session without interaction).
• Remaining from this audit: Make completed MultiCompiler cohorts authoritative without FIFO hook identity #75 (PR fix(dev): #75 — completed MultiStats cohorts are the authoritative compile identity, no FIFO hook pairing #83, with its own reviewer). Once it lands, all three redesign follow-ups are done.

[ScriptedAlchemy]

Current disposition after the meta-framework issue audit: #73 and #74 are completed and landed through PRs #84 and #85. #75 is the only remaining implementation follow-up, active in PR #83 with fresh CI running. This audit is orthogonal to the #93-#105 meta-framework stack and should close when #75 lands.

[ScriptedAlchemy]

• Make completed MultiCompiler cohorts authoritative without FIFO hook identity #75 — landed via fix(dev): #75 — completed MultiStats cohorts are the authoritative compile identity, no FIFO hook pairing #83 (squash 97e1257). Completed MultiStats cohorts are now the authoritative compile identity: the observer allocates a monotonic ordinal per global completion callback, in completion order, so identity never depends on the undocumented one-to-one FIFO pairing of before/after dev-compile hooks (the pairing queue and its loud mispair checks are removed, superseded rather than violated — misdelivered callbacks can no longer misassociate Stats at all). Pre-compile observation survives as an advisory, bounded collapse hint: an in-flight activation briefly waits for an observed compile so the newer cohort supersedes it (one visible activation per settled edit), but a dangling observation can only delay one activation by the grace budget, never wedge or fail it — preserving fix(rsc-runtime): root-cause the generation-activation wedge after a repair rebuild #39's tie-break/supersession semantics and flake: RSC runtime generation activation can wedge or go permanently stale after a repair rebuild (Node 24 CI, 2x on 2026-08-29) #38's commit-window protections (failed/no-op cohorts never bump the ordinal). Re-gated over the feat(dev): replace raw Rsbuild HMR frames with a provider-owned Runtime App reload channel (#73) #84/fix(dev): stage immutable per-environment output checkpoints before assembling runtime cohorts (#74) #85 composition: cohorts assemble from fix(dev): stage immutable per-environment output checkpoints before assembling runtime cohorts (#74) #85's immutable checkpoints keyed by the completed cohort's exact per-environment hashes, and the full local CI matrix (Node 22.19/24/26 + examples/release/micro-eval) plus 5/5 HMR e2e stress runs (2 under taskset -c 0,1) are green.

All three redesign follow-ups (#73, #74, #75) are landed; closing this audit per the disposition above.