uce/spikes/wasm-phase2/README.md

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 spikes/wasm-phase2/build_modules.sh
bash spikes/wasm-phase2/build_loader.sh
/tmp/uce/wasm-phase2/loader

Expected final line:

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.