fix(webserver): registry-owned stat poll replaces fs.watchFile baseline race

The dev bundle watch missed rebuilds that landed while the registry was constructing: fs.watchFile captures its comparison baseline with an ASYNCHRONOUS first stat, so a write racing that window is absorbed into the baseline and never reported. Standalone repro missed 24/400 same-tick rewrites; the CI flake in web-plugins.spec.ts ('watch mode: a bundle content change re-hashes the row...') was exactly this — the spec writes immediately after createHostWebPluginRegistry returns. The watch now polls from one registry-owned setInterval against a stat baseline the scan itself captures synchronously, stat-before-read: a write landing between stat and read leaves the hash newer than the baseline (next tick re-hashes to the same rev, no spurious notify); a write landing after the read leaves the baseline older (next tick detects and notifies). No blind window. The poll iterates the live table, so rescans retarget the watch for free and dispose clears one timer. Stress: real-registry same-tick rewrite 0/600 missed (was 1/300); spec watch tests 0/50. New regression test pins the same-tick-as-construction write. Its rewrite deliberately differs in size from the seed: a same-millisecond same-size rewrite is invisible to any mtime+size poll (coarse fs timestamps) — a stat-polling limit, not this regression. Loading-model Agent Note updated in both languages (pair re-recorded).
2026-07-25 01:22:46 +08:00
parent b97b1b4a3f
commit 2096050824
5 changed files with 93 additions and 51 deletions
@@ -76,7 +76,7 @@ Why is the roster a hand-written list and not a scan? Because which plugins comp

 Whether hot reload is active is a composition decision: dev graphs include the `client-hmr` row (a normal plugin package) and turn on bundle watching; prod graphs do neither.

-How does a rebuilt bundle become a reload signal? The webserver observes it itself — no builder tells it. The registry scan already holds every plugin's bundle path (`clientPath`), so in dev mode the registry stat-polls each scanned bundle file with `fs.watchFile`. Polling is by design: inotify does not fire on the weka network mount, the same reason the build-side watcher needs `--poll`. On a mtime/size change the registry re-hashes that row (`rebuilt(id)`); when the `rev` actually changed, it broadcasts a `rebuilt` frame on `GET /plugins/events` — a system SSE channel that sends the full graph on connect and `rebuilt` frames on change, presentation-only wire that never enters the session log. Watch set membership follows the table: rescans add watches for new rows and drop them for vanished ones, dispose drops all. The poll interval is a validated config field (default 500ms), not a constant. Rebuilding the bundles is any tsdown watch process's business — `scripts/dev-web.ts` remains as the watch-build entry point, its package list dshClient-discovered by scanning `packages/*/*/package.json` at startup — and builder and host share zero protocol. A torn read of a half-written bundle self-heals: the stats keep changing while the write completes, so the next poll tick re-hashes again and broadcasts the final rev.
+How does a rebuilt bundle become a reload signal? The webserver observes it itself — no builder tells it. The registry scan already holds every plugin's bundle path (`clientPath`), so in dev mode one registry-owned interval stat-polls every scanned bundle file against the stat baseline its own scan captured (synchronously, immediately before hashing that content — not `fs.watchFile`, whose asynchronous first-stat baseline silently absorbs a write landing during registry construction). Polling is by design: inotify does not fire on the weka network mount, the same reason the build-side watcher needs `--poll`. On a mtime/size change the registry re-hashes that row (`rebuilt(id)`); when the `rev` actually changed, it broadcasts a `rebuilt` frame on `GET /plugins/events` — a system SSE channel that sends the full graph on connect and `rebuilt` frames on change, presentation-only wire that never enters the session log. The poll iterates the live table, so rescans retarget the watch for free (fresh rows carry fresh baselines) and dispose clears the one timer. The poll interval is a validated config field (default 500ms), not a constant. Rebuilding the bundles is any tsdown watch process's business — `scripts/dev-web.ts` remains as the watch-build entry point, its package list dshClient-discovered by scanning `packages/*/*/package.json` at startup — and builder and host share zero protocol. A torn read of a half-written bundle self-heals: the stats keep changing while the write completes, so the next poll tick re-hashes again and broadcasts the final rev.

 On the browser side, the driver reloads one plugin per frame, serialized: