phase 5

spikes/wasm-phase2/README.md

@@ -0,0 +1,51 @@
+# spikes/wasm-phase2 — core module + membrane scaffold
+
+Phase 2 validates the next WASM step without the Phase 3 dynamic loader. The
+scaffold compiles a native UCE core subset (`Request`, `DValue`, UCEB1, print
+buffering) plus one statically linked real `.uce` page into a WASM reactor.
+A small Wasmtime C-API host provides the first membrane hostcalls, sends a UCEB1
+request context into the guest, invokes render, and reads the response from
+linear memory. `uce_host_ctx_read(ptr, cap)` follows a length-query contract:
+`ptr == 0` or `cap == 0` returns the required length; a short non-zero buffer
+also returns the required length without a partial copy; an adequately sized
+buffer receives the full context and returns the copied length.
+
+This is intentionally not the final worker. It proves the Phase 2 membrane path:
+core-owned DValue/UCEB1 code runs in WASM and a `.uce` render entry sees a
+host-provided request context through the membrane. The checked-in page uses the
+same `RENDER(Request&)` entry shape as generated units, but it is included
+directly by the scaffold rather than emitted by the UCE preprocessor.
+
+Run on `k-uce`:
+
+```bash
+bash spikes/wasm-phase2/build_modules.sh
+bash spikes/wasm-phase2/build_loader.sh
+/tmp/uce/wasm-phase2/loader
+```
+
+Expected final line:
+
+```text
+PHASE2 EXIT CRITERION: PASS
+```
+
+Files:
+
+- `core.cpp` — WASM reactor core subset and membrane decode/render entry.
+- `page.uce` — real UCE page statically linked for Phase 2 only.
+- `loader.cpp` — host runner with `uce_host_ctx_read` and `uce_host_log`.
+  Its small host-side UCEB1 encoder is spike-only; the production UCE server
+  host should use the native `ucb_encode()` implementation to avoid format drift.
+- `build_modules.sh` — wasi-sdk build for `/tmp/uce/wasm-phase2/core.wasm`.
+- `build_loader.sh` — Wasmtime C-API build for `/tmp/uce/wasm-phase2/loader`.
+
+Deferred to Phase 3:
+
+- PIC side modules and dylink loader integration.
+- Lazy unit/component loading.
+- Full `uce_lib` hostcall surface beyond the minimal context/log membrane.
+- Generator-emitted units (`.uce` preprocessor output with literal markup,
+  `__uce_set_current_request`, and generated includes) rendering through this
+  membrane; Phase 0 only proved those generated units can compile as side
+  modules.