[Impl/WASM][Plan/CWIST v3.6] CWIST WASM

[gg582]

Where WASM support actually stands today

Verified directly (real Emscripten build + node smoke test, not just reading the roadmap checkmarks):

• make wasm builds libcwist_wasm.a clean from src/core/{sstring,seq,seq_auth}, sys/err/error.c, net/http/{http,mux,query,cookie,session}.c, sys/app/{app,middleware,config,logger,shutdown,big_dumb_reply,test_client}.c, core/{siphash,utils/json_builder,utils/json_heal,utils/zod,template,html/builder,html/css_composer,validation/bind,mem/alloc,mem/arena}.c, and cJSON.c. Deliberately excludes sockets, TLS, QUIC/HTTP-3, gRPC (needs HTTP/2), WebSocket transport, threads/scheduler, compression, DB/sync clients.
• cwist_app_dispatch_memory() + <cwist/wasm/typedarray.h> (CWIST_WASM_EXPOSE_*, CWIST_WASM_INSTALL_VIEWS, Module.cwistView.{u8,i32,f64}) work end to end: make wasm-smoke actually runs a real request through a real handler and reads the response back as a zero-copy Uint8Array from JS. Confirmed passing right now.

This is a real, working foundation — but it's a library artifact you have to build yourself and wire up by hand. "Usable enough to actually reach for" needs the gaps below closed.

Gaps found while verifying

1. cwist_db WASM claim doesn't match the build. ROADMAP.md marks cwist_db_open_memory()/cwist_db_serialize() as a shipped WASM feature (v3.4 checklist), but src/core/db/db.c and lib/sqlite3/sqlite3.c are not in Makefile's WASM_SRCS. Either the roadmap entry is wrong, or the wiring was never finished — needs one or the other fixed before anyone tries to use it.
2. No WASM CI. wasm-smoke is explicitly "not part of make test since CI has no Emscripten toolchain" (Makefile comment). Nothing catches a WASM-only regression except someone manually running it — which is how gap Add doxygen style comments #1 above went unnoticed.
3. No packaged/published artifact. There's no npm package, no versioned .wasm/.js release asset, nothing beyond "clone the repo, install Emscripten yourself, run make wasm". Every consumer re-derives the EM_JS glue from scratch.
4. No docs. No docs/api/wasm.md. The only end-user-facing mention is a few lines in the Korean tutorial about css_composer.c being WASM-buildable — nothing documenting cwist_app_dispatch_memory, the TypedArray helpers, or which subsystems are actually in-scope.
5. Browser/Emscripten only. Everything here targets Module.cwistView + EM_JS, i.e. a browser or Node-with-Emscripten host. No WASI target, so CWIST handlers can't run on WASI-based edge runtimes (Cloudflare Workers, wasmtime, Fastly Compute) — which is presumably what ROADMAP.md's separate, still-🔮 "Serverless / WASM Runtime: Edge deployment target" line is actually after. Worth deciding whether that's this workstream's endgame or a genuinely separate effort.
6. No streaming. cwist_app_dispatch_memory() is whole-request-in, whole-response-out. Fine for a single edge-function invocation; not fine for anything that wants to stream a large response back to JS incrementally.
7. Session/cookie story is unclear under WASM. cookie.c/session.c compile into libcwist_wasm.a, but nothing documents or tests how session state is expected to persist across calls when the host (a Service Worker, a JS fetch handler) may not keep the same WASM instance alive between requests.
8. No example app. tests/wasm_smoke.c is a smoke test (one route, asserts response bytes), not a demonstration of a realistic app — no example showing routing + validation (zod.c, already compiled in) + templating (template.c/html/builder.c, already compiled in) actually being used together from JS.

Proposed roadmap (toward "comfortable to actually use")

Phase 1 — Fix what's already claimed done

• Resolve the cwist_db WASM gap: either wire db.c/sqlite3.c into WASM_SRCS and verify cwist_db_open_memory/cwist_db_serialize really work under Emscripten, or correct ROADMAP.md to stop claiming it.
• Add a WASM build+smoke job to CI (install Emscripten in the runner image or use emsdk's Docker image) so wasm/wasm-smoke stop being a manual-only check.

Phase 2 — Developer experience / packaging

• Write docs/api/wasm.md: what's in scope, the dispatch_memory + TypedArray pattern, a minimal end-to-end example.
• Publish a versioned build artifact (npm package wrapping the .wasm/.js glue, or a GitHub Release asset alongside native binaries) so npm install replaces "clone + install emsdk + make wasm".
• A small first-party JS wrapper module (thin fetch-shaped API over Module.cwistView/ccall) so consumers don't hand-roll EM_JS glue for the common case.

Phase 3 — Expand the supported surface

• Decide and scope a WASI target for edge runtimes, separate from the browser/Emscripten target — this is the actual gap between today's WASM support and ROADMAP's "Serverless / WASM Runtime" line.
• Streaming response support for dispatch_memory (or a parallel streaming entry point) for larger payloads.
• Document (and add a test for) the session/cookie persistence model under a request-per-call WASM host.

Phase 4 — Real example

• A full example app (routing + zod validation + template/html/builder rendering + cwist_db once Phase 1 lands) as a Cloudflare Worker or Service Worker demo, checked into example/ alongside the existing native examples.

[gg582]

Progress update (draft PR #176):

• Gap 1 resolved: db.c + sqlite3.c wired into WASM_SRCS; cwist_db_serialize -> cwist_db_open_memory round trip verified in wasm_smoke under Emscripten 5.0.0.
• Gap 2 resolved: .github/workflows/wasm.yml runs the Emscripten build + smoke on every push/PR to main/dev; green on the PR. This already proved its worth: while wiring CI it caught that the tree-wide clang-format pass had silently corrupted the EM_JS JS bodies (=> -> = >), which had broken wasm-smoke without anyone noticing. Fixed with clang-format off/on guards (EM_JS stringifies its raw macro argument, so brace-block bodies are JS, not C).
• Gap 4 started: docs/api/wasm.md initial version.

Remaining: packaging/JS wrapper (Phase 2), WASI/streaming/session-model/example app (Phases 3-4).

[gg582]

Full phase plan, taking over where the issue body stops at Phase 2. Phases 0-2 restated only as anchors; the substance is Phase 3 onward. Each phase has an exit condition so "done" is checkable, not a vibe.

Phase 0 — Foundation (done)

• libcwist_wasm.a builds clean; cwist_app_dispatch_memory() + TypedArray views pass a real wasm-smoke run.

Phase 1 — Fix what was claimed done (PR #176 in review)

• cwist_db actually in WASM_SRCS; EM_JS format-corruption fix with format-check coverage; WASM build+smoke as a CI gate (wasm.yml); docs/api/wasm.md.
• Exit: CI blocks a WASM-only regression; docs build from a clean checkout.

Phase 2 — Packaging and DX

• Versioned npm package (or release asset) wrapping .wasm/glue; first-party JS wrapper with a fetch-shaped API over Module.cwistView.
• Exit: npm install + 5 lines of JS serves a request, no Emscripten knowledge required.

Phase 3 — Supported surface expansion

1. WASI decision, recorded as an issue with a verdict: ship a WASI target, or defer and mark ROADMAP's "Serverless / WASM Runtime" line as a separate workstream. Decision input: which runtimes matter (wasmtime/Workers/Fastly) and what syscall surface dispatch_memory actually needs.
2. Streaming entry point (parallel to dispatch_memory, chunked response out), scoped to response streaming first; request streaming only if a concrete consumer needs it.
3. Session persistence model: measure real behavior across instances, then document + test the supported pattern (likely explicit session export/import at the JS boundary).
4. Bundle size report for the SQLite inclusion (unmeasured as of Phase 1 review); decide opt-out or split build from data, not instinct.

Exit: all four items land as merged PRs with tests; no open "caveat" left in docs/api/wasm.md that has no measured behavior behind it.

Phase 4 — Real example

• Full example app in example/: routing + zod validation + template/html/builder rendering + cwist_db, deployed as a Service Worker or Cloudflare Worker demo.
• Exit: example builds and runs from its README alone; CI smoke-installs it against the Phase 2 package.

Phase 5 — Production hardening

• Release integration: WASM artifact versioned and published with the same tag cadence as native releases; changelog covers the WASM surface.
• Performance pass: per-call overhead of the JS boundary measured and budgeted (cold start, dispatch latency, memory growth across calls); regressions gated in CI.
• Multi-instance story: what the host must do to run several handlers in one page/worker, documented with a test.

Exit: a tagged release ships the WASM artifact; CI enforces the perf budget.

Sequencing notes

• Phase 3.4 (bundle size) should land before Phase 2 publishes, since it can change what gets shipped. If it slips, Phase 2 publishes with SQLite included and the report becomes a fast-follow; do not block packaging on it indefinitely.
• WASI (3.1) is the only item that can reorder the sequence: if the verdict is "ship WASI now", it becomes Phase 4 and the example app shifts to Phase 5, because the example should demonstrate the primary target.

[gg582]

Phase 1 is merged (PR #176, squash commit eb6c3f7). Phase 2 is now split into two implementation issues per the phase plan above: #183 (versioned npm/release packaging) and #184 (first-party JS wrapper). Both carry their own done-when criteria; #184 depends on #183's artifact.