docs(cef): ADR-0020 CEF binding choice + Wave 2 spike findings

docs/adr/0020-cef-binding-choice-thin-cpp-host.md

@@ -0,0 +1,53 @@
+# ADR 0020: CEF integration choice — thin C++ host + Rust core (Option B)
+
+**Status:** Accepted, backed by a real hands-on spike (not a desk decision). Scope: the Wave 2 "constrained spike" required by `docs/cef/ROADMAP-CEF-DESKTOP-MIGRATION.md` §10 and its Appendix H decision scorecard. This ADR does not add CEF to the production build — no `src-tauri/` or app code changed. The spike lives outside the repository (disk-space reasons, see Consequences) and is not committed.
+
+## Context
+
+Roadmap §10 requires choosing between three CEF integration approaches before any real Wave 2 work begins:
+
+- **Option A** — Rust CEF bindings (a `cef`-style Rust crate wrapping the C++ API directly).
+- **Option B** — a thin C++ CEF host + Rust core, communicating over an FFI boundary. Rule if selected: *"C++ owns CEF integration only. It must not become the home of WorldScript business logic."*
+- **Option C** — CEF's stable C API boundary directly.
+
+The roadmap explicitly requires this be decided by "a constrained spike," not documentation review alone, and the decision must be recorded "including why rejected alternatives were rejected" (Appendix H).
+
+## Decision
+
+**Option B — thin C++ CEF host + Rust core**, on the strength of a real spike (details below), not a desk comparison.
+
+### What was actually built and run (2026-08-18)
+
+A standalone CMake/C++ project (`worldscript_host`) added as a target inside CEF's own **minimal** binary distribution (v151.3.18, Chromium 151.0.7922.138, linux64), following the standard `cefsimple`-with-Views-framework pattern (CEF's own cross-platform window toolkit, avoiding raw X11/GTK window code):
+
+- `CefApp` + `CefBrowserProcessHandler` (`WorldScriptApp`) bootstrapping a single `CefWindow`/`CefBrowserView`.
+- `CefClient` + `CefLifeSpanHandler` + `CefDisplayHandler` (`WorldScriptHandler`) tracking browser lifecycle and quitting the CEF message loop once the last browser closes.
+- A minimal Rust `staticlib` crate (`worldscript_rust_core`, one `#[no_mangle] extern "C"` function) linked directly into the C++ executable, proving the Option B FFI boundary itself — not just "does CEF alone build."
+
+**Verified, with evidence:**
+
+1. **Builds cleanly** against the CMakeLists.txt/macros CEF's own binary distribution ships (`ADD_LOGICAL_TARGET`, `SET_CEF_TARGET_OUT_DIR`, `COPY_FILES`, `SET_EXECUTABLE_TARGET_PROPERTIES`) — no custom build-system invention needed, matching Option B's "closest to upstream CEF examples" advantage in practice, not just on paper.
+2. **Launches and renders** under a Linux Xvfb virtual framebuffer (`about:blank`) with no fatal error. GPU-acceleration warnings were observed and are recorded honestly rather than glossed over: `MESA-INTEL: warning: Bay Trail Vulkan support is incomplete` and `Installed VAAPI version is too old (min 1.17, installed 1.14)` — Chromium fell back to software rendering (bundled SwiftShader) without crashing. This is a real Linux/GPU compatibility data point for the eventual compatibility matrix (roadmap §44), not yet a pass/fail verdict on any specific hardware tier.
+3. **Repeated start/close cycles (3×) all completed with a clean process tree** — no orphaned renderer/GPU/zygote processes after each cycle, verified by checking for the specific PIDs after a delay (see the shutdown-timing finding below). This is the literal Wave 2 exit-criterion language ("clean repeated start/close cycles pass").
+4. **Option B's actual FFI boundary works**, proven in isolation (a minimal C++ program linking only against the compiled Rust `staticlib` and calling into it, decoupled from CEF's own multi-process complexity) — the call returns the expected sentinel value from compiled Rust code, not a stub.
+
+**A real operational finding, not speculative:** CEF/Chromium's shutdown after SIGTERM is not instantaneous — an immediate post-signal process check can show a still-running process for a few seconds before it exits on its own. Do not conclude "hung" from an immediate check; re-check after a short grace period. (Captured properly in `docs/cef/knowledge/subprocess-and-shutdown.md`.)
+
+**A real dev-environment finding:** on this constrained (~3.7GB RAM) Linux dev machine, the CEF-linking step (against `libcef.so` + `libcef_dll_wrapper.a`) was unreliable when tracked as a foreground/background job by the local agent tooling used for this spike, but completed successfully once fully detached from that tooling's own process tracking (`setsid`/`nohup`/`disown`). Chromium's own default linker-optimization flags (`--gc-sections`, `-O1`) were also dropped in favor of `ld.gold` for this spike's build, trading link-time whole-program analysis for a lower memory/time footprint appropriate to constrained hardware; a CI/production build on adequately-resourced hardware should keep the stronger flags. This is a local-tooling/hardware note, not a CEF or Rust defect — recorded here so a future contributor on similar hardware doesn't waste time re-diagnosing it.
+
+### Why Option A and Option C were not selected
+
+Not run as parallel spikes — Option B's spike succeeded cleanly against its own stated risks (binding maturity/unsafe surface for A; verbosity for C are the roadmap's own framing) with no blocking issue encountered, and it most directly satisfies the roadmap's explicit rule that C++ must not become a home for business logic — a thin host that only talks to CEF, with all real logic in the already-proven Rust FFI boundary, is the most direct implementation of that rule. Per Appendix H's own instruction, this counts as "why rejected" for A and C: no spike evidence surfaced a reason to prefer either over B, and B's own risks (additional C++ toolchain, an FFI boundary) were the ones actually paid down by this spike, not merely assumed away.
+
+This is not a closed door — if Wave 2's later, larger integration work surfaces a concrete blocker specific to Option B, revisit via a superseding ADR, not a silent pivot.
+
+## Consequences
+
+- `packages/desktop-contracts` and the Wave 1 `DesktopPlatform` abstraction are unaffected by this ADR — no CEF adapter exists yet (Wave 2+ per the original Wave 1 plan), and this ADR does not change that.
+- The spike code itself (CMake target, C++ sources, Rust crate, and the ~1.5GB extracted CEF SDK) lives outside this repository (a local scratch directory) and is **not** committed — the CEF binary distribution is a large vendored third-party download that does not belong in git history, and the C++/Rust source is a throwaway proof, not yet production code. A future real Wave 2 PR ("bootstrap Chromium Embedded Framework host," per the roadmap's Appendix G PR sequencing) re-creates the equivalent host inside `src-tauri`'s eventual CEF-era replacement (or a sibling directory), fetched via a build script rather than committed binaries, with the real Cargo↔CMake integration (e.g. `corrosion`) replacing this spike's hardcoded `.a` path.
+- `docs/cef/knowledge/subprocess-and-shutdown.md` and `docs/cef/knowledge/linux-runtime-notes.md` get their first real (non-speculative) content from this spike's findings, per their own "do not fill in speculatively" instruction.
+- `docs/architecture/native-readiness.md` gets a Wave 2 snapshot noting this spike's evidence.
+- Rust becomes the confirmed home for CEF-era business logic, consistent with ADR-0019 point 3 ("Rust becomes increasingly authoritative for critical desktop concerns").
+- Still open, explicitly deferred, not assumed: sandbox posture (this spike ran with `no_sandbox = true`; roadmap §12's real security model is separate scope), the full Linux/GPU compatibility matrix across vendors/desktop environments, packaging, and the #332 PWA/Tauri/CEF performance comparison harness (roadmap Wave 3) — none of those are answered by this ADR.
+
+**Rejected alternative:** deciding the binding approach from documentation alone. Rejected because the roadmap itself requires a hands-on spike, and this session's own experience confirms why — real build-system integration details (the `ADD_LOGICAL_TARGET`/`SET_CEF_TARGET_OUT_DIR` macros not being auto-invoked, the shutdown-timing false-positive, the local link-memory tooling quirk) were not visible from the CEF distribution's README alone.

docs/architecture/native-readiness.md

@@ -49,3 +49,17 @@ The Wave 1 PR A snapshot left three DEBT rows marked "not yet scheduled to a spe
 ## Next scoring checkpoint
 
 Re-score "Platform APIs adapter-contained" again once `services/logger.ts`'s JSONL sink migrates (Wave 5/7, see above). Re-score the three newly-scheduled rows at each wave's exit (Wave 4 typed-IPC-v1, Wave 5 domain extraction).
+
+## Snapshot: Wave 2 binding spike (ADR-0020, `docs/cef/CEF-BINDING-DECISION-SCORECARD.md`)
+
+Wave 2's first deliverable — the CEF binding/C++ decision — is now backed by a real hands-on spike, not a desk pick. Full scorecard: `docs/cef/CEF-BINDING-DECISION-SCORECARD.md`. This snapshot only tracks what changes for *this* readiness table; the roadmap's own Wave 2 exit criteria (Early Accessibility Gate, "no production-critical lifecycle assumption remains undocumented") are broader than this single row and are **not** claimed as met here.
+
+| Check | Result | Owner | Notes |
+|---|---|---|---|
+| CEF binding/integration approach decided | **PASS** | cef-runtime | Option B (thin C++ CEF host + Rust core) chosen and spiked with real evidence: builds against CEF's own binary-distribution CMake macros, launches under Xvfb, survives 3 repeated start/close cycles with a clean process tree, and its core premise (a working Rust↔C++ FFI boundary) is proven in isolation. See ADR-0020. |
+| CEF renders reliably on Linux dev systems | DEBT — partial | cef-runtime, Wave 2 (in progress) | One data point only: one dev machine, one GPU (Intel integrated, software-fallback path exercised), X11/Xvfb only, no sandbox. Exit condition (unchanged from roadmap §2's Wave 2 exit criteria): broader Linux/GPU/display-server matrix coverage (Appendix A.3) before this can flip to PASS. |
+| CEF lifecycle assumptions documented | DEBT — partial | cef-runtime, Wave 2 (in progress) | `docs/cef/knowledge/subprocess-and-shutdown.md` now has one real (non-speculative) finding — SIGTERM shutdown is not instantaneous, don't false-positive an immediate post-signal check — but it is explicitly flagged as not yet backed by a committed/CI-run test, per the doc's own evidence-link discipline. Exit condition: a real test + CI job, not just a spike observation. |
+| Early Accessibility Gate | Not yet attempted | cef-runtime, Wave 2 | Out of this spike's scope entirely — no accessibility tree/API integration was touched. |
+| Sandbox posture | Not yet attempted | desktop-security, Wave 2/3 (roadmap §12) | Spike explicitly ran with `no_sandbox=true`; zero evidence either way on this row. |
+
+**Overall for this snapshot**: 1 PASS, 2 explicit DEBT-in-progress rows (each with a concrete exit condition, not open-ended), 2 not-yet-attempted rows correctly left blank rather than assumed. No row is marked PASS without the evidence cited above.

docs/cef/CEF-BINDING-DECISION-SCORECARD.md

@@ -0,0 +1,32 @@
+# CEF Integration Decision Scorecard
+
+Fills in the empty template from `docs/cef/ROADMAP-CEF-DESKTOP-MIGRATION.md` Appendix H, per ADR-0020. Scored **only** where the Wave 2 spike produced real evidence — a blank/"not tested" cell means exactly that, not an assumed pass.
+
+**Decision: Option B (thin C++ CEF host + Rust core).** See `docs/adr/0020-cef-binding-choice-thin-cpp-host.md` for the full rationale and spike description.
+
+| Criterion | Rust binding (A) | Thin C++ host (B) | C API (C) |
+|---|---|---|---|
+| Linux support | not spiked | **Partial** — built and ran on one Ubuntu 22.04/X11/Xvfb machine, CEF's own officially-tested target for this version; packaged/clean-machine runtime compatibility remains unproven (§44.3) | not spiked |
+| Windows support | not spiked | not spiked (Linux-only spike) | not spiked |
+| macOS support | not spiked | not spiked (Linux-only spike) | not spiked |
+| Sandbox | not spiked | Not exercised — spike ran with `no_sandbox=true`; roadmap §12's real sandbox posture is separate, later scope | not spiked |
+| Renderer callbacks | not spiked | Partial — browser-process handlers (`CefLifeSpanHandler`/`CefDisplayHandler`) fired correctly across 3 repeated create/close cycles; renderer-process-specific callbacks (`CefRenderProcessHandler`/`CefRenderHandler`) were not implemented or tested this spike | not spiked |
+| GPU/crash callbacks | not spiked | Partial — observed real GPU-fallback warnings (Bay Trail Vulkan incomplete, VAAPI 1.14 < required 1.17) with a clean software-render fallback (SwiftShader), not a crash; no deliberate crash-callback test performed yet | not spiked |
+| Packaging | not spiked | not spiked (this was a build+run spike, not a packaging spike) | not spiked |
+| Upstream docs | not spiked | **Good** — CEF's own `cefsimple`-pattern conventions and shipped CMake macros were directly usable with only the expected per-target additions (`ADD_LOGICAL_TARGET`, `SET_CEF_TARGET_OUT_DIR` — not auto-invoked by the minimal distribution, but documented in the macro file itself) | not spiked |
+| Memory/lifetime safety | not spiked | Noted, not yet stress-tested: CEF's own shutdown sequence takes a few real seconds after SIGTERM — confirmed clean (no permanent orphans) but not instantaneous; see `docs/cef/knowledge/subprocess-and-shutdown.md` | not spiked |
+| FFI complexity | n/a (no C++/Rust FFI boundary in this option) | **Proven low** — a minimal `#[no_mangle] extern "C"` Rust `staticlib`, linked via a plain `.a` path, called correctly and returned the expected value; no binding-generation tooling needed for a function this simple | n/a for this spike's scope |
+| Maintenance | not spiked | Reasonable expectation, not yet tested across a version bump — the spike used one pinned CEF version only | not spiked |
+| CI complexity | not spiked | Not yet run in CI. Real, evidence-based local-dev finding: linking against `libcef.so`/`libcef_dll_wrapper.a` needed `ld.gold` + reduced optimization flags + full process detachment from this session's own tooling to complete reliably on constrained (~3.7GB RAM) hardware — a CI runner with more memory may not need any of this, but it should be verified, not assumed | not spiked |
+| Rust-core fit | not spiked | **Proven** — the FFI boundary this option's whole premise depends on (C++ owns CEF only, Rust owns logic) works, verified in isolation from CEF's own process complexity | not spiked |
+
+## What this scorecard does *not* claim
+
+- Cross-platform parity (Windows/macOS) — zero evidence either way; this was a Linux-only spike matching the roadmap's own Wave 2 exit criterion ("renders reliably... on Linux development systems").
+- Sandbox viability — deliberately disabled for this spike; a real security-model evaluation is separate, later scope (roadmap §12, Wave 3+).
+- Production packaging, updater, or crash-reporting pipeline integration — none of these were exercised.
+- A verdict on Options A or C's actual viability — they were not spiked in parallel; see ADR-0020's "why rejected" section for the reasoning behind not spiking them given B's clean result.
+
+## Re-scoring triggers
+
+Re-score this table (not just append to it) when: Windows/macOS support is spiked, sandbox mode is enabled and tested, a second CEF version is tried (to exercise "maintenance"), or this moves into real CI (to score "CI complexity" honestly instead of narratively).

docs/cef/OWNERSHIP.yaml

@@ -68,6 +68,29 @@ documents:
     related_ci: []
     driftCheckTool: "planned — not implemented, see Wave 1"
 
+  - path: docs/adr/0020-cef-binding-choice-thin-cpp-host.md
+    tier: A
+    owner_role: cef-runtime
+    backup_role: desktop-architecture
+    last_verified:
+      worldscript: "v1.27.1"
+      cef: "151.3.18+gbeff58d+chromium-151.0.7922.138"
+    review_days: 90
+    related_ci: []
+    driftCheckTool: "planned — not implemented, see Wave 1"
+
+  - path: docs/cef/CEF-BINDING-DECISION-SCORECARD.md
+    tier: A
+    owner_role: cef-runtime
+    backup_role: desktop-architecture
+    last_verified:
+      worldscript: "v1.27.1"
+      cef: "151.3.18+gbeff58d+chromium-151.0.7922.138"
+    review_days: 90
+    related_ci: []
+    driftCheckTool: "planned — not implemented, see Wave 1"
+    note: "Appendix H scorecard, filled in per ADR-0020 — re-score triggers are listed in the doc itself, not just the review_days cadence."
+
   - path: docs/cef/knowledge/cef-architecture-primer.md
     tier: A
     owner_role: cef-runtime
@@ -106,22 +129,26 @@ documents:
     tier: A
     owner_role: cef-runtime
     backup_role: rust-core
-    last_verified: null
+    last_verified:
+      worldscript: "v1.27.1"
+      cef: "151.3.18+gbeff58d+chromium-151.0.7922.138"
     review_days: 90
     related_ci:
       - cef-learning-harness
     driftCheckTool: "planned — not implemented, see Wave 1"
-    note: "Skeleton only — Status: Not started"
+    note: "Preliminary spike evidence only (ADR-0020) — not yet backed by a committed/CI-run test; see the doc's own evidence-link discipline note."
 
   - path: docs/cef/knowledge/linux-runtime-notes.md
     tier: A
     owner_role: cef-runtime
     backup_role: desktop-architecture
-    last_verified: null
+    last_verified:
+      worldscript: "v1.27.1"
+      cef: "151.3.18+gbeff58d+chromium-151.0.7922.138"
     review_days: 90
     related_ci: []
     driftCheckTool: "planned — not implemented, see Wave 1"
-    note: "Skeleton only — Status: Not started"
+    note: "Preliminary spike evidence only (ADR-0020) — one machine, one GPU, X11 only; not a compatibility contract yet."
 
   - path: docs/cef/knowledge/debugging-and-crash-playbook.md
     tier: A
@@ -160,7 +187,7 @@ documents:
     backup_role: desktop-security
     last_verified:
       worldscript: "v1.27.1"
-      cef: "not applicable — pre-CEF-selection"
+      cef: "151.3.18+gbeff58d+chromium-151.0.7922.138"
     review_days: 180
     related_ci: []
     driftCheckTool: "planned — not implemented, see Wave 1"