fix(utoopack): unify native development ownership (#118)

Author: xusd320

ARCHITECTURE.md

@@ -242,6 +242,20 @@ one fixed config, CoreGraph, BuildPlan, plugin-hook set, generated IR image,
 and bundler controller; adapters are never asked to replace those inputs in
 place.
 
+The Utoopack adapter keeps one native-owner Worker for the lifetime of
+`ev dev`. That Worker is the only development realm that loads Utoopack's
+native binding: it registers the process-global loader scheduler and owns all
+sequential native Projects. Individual Sessions still own and fully release
+their Project, HTTP server, subscriptions, and persistent-cache lock. The host
+exchanges cloneable Session commands with the owner and retains only callbacks
+that cannot cross the Worker boundary, such as function-valued proxy rewrites.
+Successful Utoopack process-exit requests are converted into Session-close
+acknowledgements inside the owner; unexpected exits, scheduler failures, and
+shutdown timeouts poison the owner and prevent an overlapping replacement.
+Production build and development ownership cannot be mixed in one process;
+development also rejects a host-preloaded Utoopack binding before it creates
+the owner Worker.
+
 Framework watchers cover opaque config/plugin inputs, semantic analysis
 dependencies, and Page/API topology. They compare file content and stable
 directory topology, ignore generated output, and fall back from native events

CHANGELOG.md

@@ -6,6 +6,15 @@ All notable changes to evjs are documented here. Releases follow [Semantic Versi
 
 ## [Unreleased]
 
+### 🐛 Bug Fixes
+
+- **Single-realm Utoopack native ownership** — `ev dev` now keeps Utoopack's
+  native binding, process-global loader scheduler, loader-worker pool, and all
+  sequential Projects in one long-lived Worker. Immutable Session replacement
+  runs complete Project, server, subscription, and persistent-cache cleanup
+  without moving native callbacks across Worker environments; owner and
+  shutdown failures remain fail-stop instead of starting overlapping Projects.
+
 ---
 
 ## [0.3.15] — 2026-08-20

package-lock.json

@@ -11,6 +11,25 @@ Its declared capabilities are the authoritative boundary: conventional
 server-rendered Page entries are supported, while plans that require RSC or
 PPR fail during framework preflight.
 
+## Development Native Ownership
+
+Utoopack development uses one long-lived native-owner Worker for the complete
+`ev dev` command. Ownership is intentionally split by lifetime:
+
+| Lifetime | Owner | Responsibility |
+| --- | --- | --- |
+| `ev dev` process | Framework host | Session protocol, function-valued proxy rewrites, and framework supervision. It does not load Utoopack's native binding. |
+| `ev dev` process | Native-owner Worker | Utoopack's native binding, process-global loader scheduler, loader-worker pool, and every sequential native Project. |
+| Immutable Session | Native-owner Worker | One Project, development server, subscriptions, and persistent-cache lock. These close completely before the next Session starts. |
+
+Session replacement runs Utoopack's own graceful cleanup inside the owner and
+converts its successful process exit into a Session boundary. The Worker then
+remains idle for the next immutable Session. Owner startup failures, loader
+scheduler failures, unexpected exits, and shutdown timeouts are fail-stop; the
+host never creates a second native owner in the same process. Startup also
+rejects a host that has already loaded Utoopack's native binding, because that
+would recreate cross-environment native ownership.
+
 ## Usage
 
 This adapter is enabled by default in evjs. You do not need to configure it manually unless you are overriding another bundler.