feat(plugins)!: refuse watch/rebuild capture instead of silently attesting stale content

[exo-nikita]

The hazard

All three bundler plugins dedupe file capture with an instance-level #seen Set that is keyed by path and never cleared (and State.write's compare-and-skip caches are content-blind in the same way). On a watch / dev-server rebuild where a file's bytes change, #seen skips the re-capture: the emitted output uses the new bytes while the stasis bundle/lockfile silently keeps attesting the old ones. Verified empirically by driving the esbuild plugin callbacks across two builds — an attestation tool quietly attesting the wrong content.

The decision

Do not fix the staleness by tracking content changes across rebuilds. Instead, make watch/rebuild capture explicitly unsupported: each plugin refuses it loudly at the first rebuild signal, before anything stale can be recorded.

What now refuses, and where

• webpack (stasis-plugins/src/webpack.js): capture mode taps compiler.hooks.watchRun and throws StasisWebpack: watch mode is not supported for capture .... watchRun fires only under compiler.watch() and before the first watch build, so the whole watch session is rejected up front (a sync tap's throw propagates through the AsyncSeriesHook and fails the watcher). The done hook's now-dead watching immediate-write arm is removed; single-compiler write-on-done and the MultiCompiler deferred flush are unchanged.
• esbuild (stasis-plugins/src/esbuild.js): capture mode registers an onStart guard that fails the second build start the esbuild-idiomatic way — returned errors (StasisEsbuild: watch/rebuild is not supported for capture ...). Rebuilds re-fire onStart against the same setup registrations, and the counter lives on the plugin instance, so it also catches one instance reused across two esbuild.build() calls (same staleness hazard). onEnd's clean-build gate then skips the write.
• metro (stasis-plugins/src/metro.js): the serializer throws on its second invocation (StasisMetro: watch/dev-server rebuilds are not supported for capture -- use a one-shot metro build``). A one-shot metro build serializes once; only a dev server (`metro start`) re-invokes it per rebuild, and Metro hands the serializer no watch signal on the first build, so the first rebuild is the earliest refusal point. The class-level KNOWN LIMITATIONS block now documents the enforced one-shot stance.

Deliberately untouched

• Load mode (bundle=load) in all three plugins: it serves immutable attested bytes back into the build (getFile re-verifies hashes on every read), so rebuilds have no drift hazard — and Metro's load path (the companion worker transformer) legitimately runs under a dev server. The esbuild plugin registers no onStart in load mode.
• stasis-core: State.write's compare-and-skip caches stay — they still serve the webpack MultiCompiler multi-done case.

Tests

• tests/webpack-defer-write.test.js: the watch case now pins the refusal — watchRun throws and nothing writes on any path (immediate or deferred).
• tests/plugins-rebuild-refusal.test.js (new, dep-free like the other stub suites): drives esbuild's setup() with stub build hooks (second onStart returns the error; a fresh setup() on a reused instance still refuses; load mode registers no guard) and metro's customSerializer with a minimal mock graph (second serialization throws before the base serializer runs).
• Prose-only touch-ups where tests/comments described the old watch-capture flow (webpack-fs.test.js, state-write-skip.test.js, state-split-bundle.test.js). No README/doc promises watch capture, so no doc changes were needed.

Ran locally (Node 22, stub-driven, all green): plugins-rebuild-refusal, webpack-defer-write, webpack-fs, metro-fs, metro, metro-transformer, plugins, state-write-skip, state-split-bundle. The real-bundler suites (webpack*, esbuild*, cli/build-cmd) need installed devDependencies + Node 24 — covered by CI.

🤖 Generated with Claude Code

https://claude.ai/code/session_01M16Lwt8cM1azwev94UP81X

---

Generated by Claude Code