Stage ABI-scoped unit generations

docs/setup.md

@@ -215,7 +215,9 @@ Important settings:
 - `FCGI_SOCKET_MODE` and `CLI_SOCKET_MODE` are octal permission modes applied after socket bind. Prefer tightening `FCGI_SOCKET_MODE` to `0660` when nginx/Apache can share a trusted group with the UCE worker.
 - `SITE_DIRECTORY` is the public site tree to scan for `.uce` files. Use `/var/www/html` when the web root is outside the runtime tree; relative paths are resolved from the runtime working directory. Installed regression gate scripts derive their temporary test root from this setting unless `UCE_TEST_SITE_DIRECTORY` is explicitly provided.
 - `HTTP_DOCUMENT_ROOT` is the root used by the built-in HTTP/WebSocket listener when it resolves upgrade requests. Set it to the same web root as nginx/Apache.
-- `BIN_DIRECTORY` stores generated C++, wasm artifacts, compile output, and runtime caches.
+- `BIN_DIRECTORY` stores runtime state plus ABI-scoped unit generations. Unit
+  C++, wasm, serialized modules, source maps, and compile diagnostics live in
+  `units-c<compiler ABI>-w<core ABI>` so an upgrade cannot mix generations.
 - `TMP_UPLOAD_PATH` and `SESSION_PATH` must be writable by the runtime.
 - `SESSION_COOKIE_SECURE=1` adds the `Secure` attribute to UCE-managed session cookies and should be used for HTTPS-only deployments. Leave it `0` only for local/plain-HTTP development.
 - `MYSQL_PERSISTENT_POOL_SIZE` caps credential-keyed connections retained by each Wasm worker. The default `8` is clamped to `64`; set it to `0` to restore request-lifetime connections. Cached sessions are reset before reuse.
@@ -697,7 +699,14 @@ Common compile footguns:
 - `WASMTIME_HOME` does not point at a tree with Wasmtime headers and `libwasmtime.so`.
 - A previous failed compile left stale `.compile.txt`, `.wasm-check.txt`, or partial `.wasm` files under `BIN_DIRECTORY`.
 
-Failed compile output is persisted under the unit's generated path in `BIN_DIRECTORY` and may be reused until the source or compiler inputs change. First fix the source/toolchain issue and reload the page. If the cache itself is suspect, stop UCE, move only the affected unit artifact files or directory aside, and restart so the runtime recompiles from source. Avoid deleting the whole `BIN_DIRECTORY` unless you intentionally want a full rebuild.
+Failed compile output is persisted under the unit's ABI-generation path in
+`BIN_DIRECTORY` and may be reused until the source or compiler inputs change.
+The managed `restart` command first runs the new binary's `--precompile` mode as
+the configured service user while the old service remains live. It restarts
+systemd only after every scanned unit compiles and serializes successfully.
+First fix source/toolchain failures and retry; do not remove the prior generation,
+which remains the rollback path. Avoid deleting the whole `BIN_DIRECTORY` unless
+you intentionally want a full rebuild and have accepted losing rollback artifacts.
 
 ### CLI commands fail
 

docs/wasi-sdk-toolchain.md

@@ -47,7 +47,9 @@ Treat WASI SDK upgrades like runtime dependency upgrades:
 2. Record the new release and checksum here.
 3. Rebuild `bin/wasm/core.wasm` with `scripts/build_core_wasm.sh`.
 4. Rebuild the native runtime with `scripts/build_linux.sh`.
-5. Clear or invalidate stale unit wasm artifacts by bumping `UCE_UNIT_ABI_VERSION` when required, or by removing affected generated artifacts under `BIN_DIRECTORY`.
+5. Bump the compiler or core ABI constant in `src/wasm/abi.h` when required.
+   The managed restart precompiles the resulting isolated unit generation before
+   switching workers; do not overwrite or delete the previous generation.
 6. Run the full CLI suite including wasm kill tests:
 
 ```bash

docs/wasm-runtime-architecture.md

@@ -232,6 +232,14 @@ refreshes the epoch deadline before its first guest call. Otherwise a component
 whose compilation outlasted the guest CPU budget would immediately trap in the
 following allocator/relocation call even though no guest loop consumed it.
 
+Unit artifacts live beneath an ABI-generation directory such as
+`BIN_DIRECTORY/units-c12-w7`: `c12` is the compiler/unit-metadata ABI and `w7`
+is the runtime core ABI. Old and new service binaries therefore never publish
+or read the same unit path during an ABI transition. The managed restart builds
+and serializes the complete next generation before stopping the old service;
+failure aborts the switch and leaves the running generation intact. Old
+generation directories are retained as an explicit rollback path.
+
 The proactive compiler and request workers coordinate through per-unit file
 locks and a lock-protected demand-priority queue under `BIN_DIRECTORY`. A small
 priority-only compiler process drains that queue independently of the full-site