Resolve wasm traps to unit source

docs/setup.md

@@ -46,6 +46,8 @@ UCE also requires two non-vendored dependencies. WASI SDK is load-bearing at run
   - `/opt/wasi-sdk/bin/clang++`
   - `/opt/wasi-sdk/bin/wasm-ld`
   - `/opt/wasi-sdk/bin/llvm-objcopy`
+  - `/opt/wasi-sdk/bin/llvm-nm`
+  - `/opt/wasi-sdk/bin/llvm-dwarfdump`
 
 You can use different install locations by setting environment variables before building and in the systemd service environment:
 
@@ -100,6 +102,8 @@ The expected directories are:
 /opt/wasi-sdk/bin/clang++
 /opt/wasi-sdk/bin/wasm-ld
 /opt/wasi-sdk/bin/llvm-objcopy
+/opt/wasi-sdk/bin/llvm-nm
+/opt/wasi-sdk/bin/llvm-dwarfdump
 ```
 
 Install the WASI SDK:
@@ -135,6 +139,8 @@ test -f /opt/wasmtime/lib/libwasmtime.so
 /opt/wasi-sdk/bin/clang++ --version
 /opt/wasi-sdk/bin/wasm-ld --version
 /opt/wasi-sdk/bin/llvm-objcopy --version
+/opt/wasi-sdk/bin/llvm-nm --version
+/opt/wasi-sdk/bin/llvm-dwarfdump --version
 ```
 
 If your paths differ, export the variables for manual builds:
@@ -687,7 +693,7 @@ Common compile footguns:
 
 - `WASM_COMPILE_SCRIPT` is unset or points at a removed script such as `scripts/compile`; set it to `scripts/compile_wasm_unit`.
 - `scripts/check_unit_wasm.py` is missing or not executable; `scripts/compile_wasm_unit` calls it after linking each unit.
-- `WASI_SDK` does not point at the pinned tree with `clang++`, `wasm-ld`, `llvm-objcopy`, and `llvm-nm`; run `scripts/install_wasi_sdk.sh --check-only`.
+- `WASI_SDK` does not point at the pinned tree with `clang++`, `wasm-ld`, `llvm-objcopy`, `llvm-nm`, and `llvm-dwarfdump`; run `scripts/install_wasi_sdk.sh --check-only`.
 - `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`.
 

docs/wasi-sdk-toolchain.md

@@ -31,9 +31,13 @@ UCE expects these executables on each deployment host:
 /opt/wasi-sdk/bin/wasm-ld
 /opt/wasi-sdk/bin/llvm-objcopy
 /opt/wasi-sdk/bin/llvm-nm
+/opt/wasi-sdk/bin/llvm-dwarfdump
 ```
 
 `llvm-nm` is used by `scripts/check_unit_wasm.py`, which is called by `scripts/compile_wasm_unit` after linking each unit.
+`llvm-dwarfdump` is used at unit compile time to extract the compact, out-of-band
+source map before debug sections are stripped from the runtime artifact. The
+map is consulted only on a wasm trap.
 
 ## Upgrade policy
 

docs/wasm-runtime-architecture.md

@@ -222,8 +222,8 @@ Freshness still stats every distinct source on every entry check. Exact repeated
 load paths are deduplicated before canonicalization, while distinct aliases are
 resolved independently so symlink retargets remain immediately visible.
 When a current serialized module exists, the worker scans wasm section headers
-and reads only `dylink.0` and `uce.abi`; it does not fault the multi-megabyte code
-and data bodies into every new worker. A missing/stale/invalid serialized module
+and reads only `dylink.0`, `uce.abi`, and the tiny `uce.module` identity; it does
+not fault the code and data bodies into every new worker. A missing/stale/invalid serialized module
 still reads, validates, compiles, and republishes the complete wasm artifact.
 The proactive compiler also creates that serialization immediately after source
 compilation, keeping first-worker native compilation off the request path.
@@ -257,6 +257,19 @@ intentional unreadable-source regression request as an expected source-read
 failure, keeping production log scans focused on real runtime failures while
 preserving the failing compile result and diagnostic artifacts.
 
+Unit linking retains DWARF only long enough for
+`scripts/build_unit_source_map.py` to extract a compact address/file/line table.
+The published `.wasm` is debug-stripped and the table is stored beside it as
+`.wasm.source-map`, keyed to the exact temporary module identity recorded in
+the wasm's `uce.module` custom section. Normal module loading never reads this
+sidecar. On a Wasmtime trap, the worker uses structured frame module offsets to
+load only the matching map and appends source locations to the error. A missing,
+stale, or malformed map is deliberately non-fatal: the ordinary named wasm
+backtrace remains available. Generated C++ uses a `#line` directive naming the
+original `.uce` file, so application frames resolve to application source rather
+than the generated cache file. Artifact invalidation removes the wasm, serialized
+module, and source map together.
+
 ---
 
 ## 4. The workspace runtime