qnbs · qnbs · Aug 19, 2026 · Aug 19, 2026
@@ -10,7 +10,7 @@ This is an engineering gate (roadmap §4.11.6), not a training checklist. `WS-CE
 ```yaml
 cef_competency:
   binding_model_documented: true   # docs/adr/0020-cef-binding-choice-thin-cpp-host.md
-  lifetime_model_reviewed: false
+  lifetime_model_reviewed: true    # docs/cef/knowledge/threading-and-lifetimes.md (PR #390) — UI-thread callbacks + ref-counting/callback-lifetime; IO thread and async cancellation still untouched
   repeated_shutdown_ci: true       # scripts/cef/run-launch-cycle-proof.mjs, cef-learning-harness CI job (PR #388)
   renderer_crash_ci: true          # chrome://crash + OnRenderProcessTerminated + browser-process survival, cef-learning-harness CI job (PR #392)
   sandbox_smoke: false
@@ -24,19 +24,19 @@ CI validation of this block ("fail CI when a required item for the active progra
 
 | Domain | Status | Evidence |
 |---|---|---|
-| CEF architecture (process model, browser/frame/client ownership, message loop, shutdown ordering, subprocess packaging, sandbox expectations) | Partial | Process model, message loop, and shutdown ordering all have real working code + CI proof (`apps/desktop-cef/`, PR #388). Subprocess *resource layout* (unpackaged CEF build output — `COPY_FILES`) is confirmed, but real shipped/installer packaging is separate, unproven, later scope. No dedicated architecture-primer doc exists yet (`docs/cef/knowledge/cef-architecture-primer.md` still skeleton), and sandbox expectations have zero evidence. |
-| CEF threading & lifetime rules (UI-thread callbacks, IO thread, ref-counted objects, callback lifetime, async cancellation, shutdown races) | Partial | `CEF_REQUIRE_UI_THREAD()` used throughout; `IMPLEMENT_REFCOUNTING`/`CefRefPtr` applied correctly; a real callback-lifetime lesson learned and fixed (`base::Unretained` vs. a plain `CefTask` — see `apps/desktop-cef/src/worldscript_handler.cpp`). No dedicated review doc yet (`docs/cef/knowledge/threading-and-lifetimes.md` still skeleton); IO thread and async-cancellation patterns untouched. |
+| CEF architecture (process model, browser/frame/client ownership, message loop, shutdown ordering, subprocess packaging, sandbox expectations) | Partial | Process model, message loop, and shutdown ordering all have real working code + CI proof (`apps/desktop-cef/`, PR #388), now written up in `docs/cef/knowledge/cef-architecture-primer.md` (PR #390, no longer a skeleton). Subprocess *resource layout* (unpackaged CEF build output — `COPY_FILES`) is confirmed, but real shipped/installer packaging is separate, unproven, later scope. Sandbox expectations still have zero evidence. |
+| CEF threading & lifetime rules (UI-thread callbacks, IO thread, ref-counted objects, callback lifetime, async cancellation, shutdown races) | Partial | `CEF_REQUIRE_UI_THREAD()` used throughout; `IMPLEMENT_REFCOUNTING`/`CefRefPtr` applied correctly; a real callback-lifetime lesson learned and fixed (`base::Unretained` vs. a plain `CefTask` — see `apps/desktop-cef/src/worldscript_handler.cpp`), now written up in `docs/cef/knowledge/threading-and-lifetimes.md` (PR #390, no longer a skeleton). IO thread, render-process-side code, and async-cancellation patterns remain untouched. |
 | Rust binding layer (crate/version, unsafe/FFI boundary, wrapper ownership, API coverage gaps, upgrade procedure) | Partial | `apps/desktop-cef/rust-core/` (`worldscript_rust_core`, Corrosion-linked) — FFI boundary proven inside the real CEF host in CI (PR #388), not just an isolated test. No upgrade procedure written yet (`docs/cef/knowledge/binding-upgrade-playbook.md` still skeleton); API coverage is currently one trivial function, not representative of real surface area. |
 | Cross-platform native host (Linux loader/resource layout, Windows process/installer/sandbox, macOS bundle/signing, window lifecycle, high-DPI, IME/a11y) | Partial (Linux only) | Linux loader/resource layout confirmed via a real filesystem listing in CI (`docs/cef/knowledge/linux-runtime-notes.md`); a real cwd-relative-path startup bug found and fixed. Zero Windows/macOS evidence. Window lifecycle proven for open/close only — high-DPI and IME/a11y untouched. |
 | Operational CEF (crash reporting, symbol handling, version-update automation, sandbox verification, packaging deps, runtime diagnostics) | Partial | Packaging deps: `scripts/cef/check-linux-runtime-deps.mjs` (CI-run). Runtime diagnostics: `scripts/cef/print-cef-version-diagnostics.mjs` + verbose CEF logging (`--enable-logging=stderr --v=1`) added mid-debugging this wave. Crash reporting: proven in CI (PR #392) — `crash_reporter.cfg` + `CefCrashReportingEnabled()` + a deliberately induced renderer crash (`chrome://crash`) produced a real Crashpad `.dmp` file (the harness's actual assertion) under an overridden `BREAKPAD_DUMP_LOCATION`, alongside Crashpad's own `.meta`/`settings.dat` housekeeping files (observed, not independently asserted); the browser process survived. Symbol handling (decoding a dump into a stack trace) needs `dump_syms`/`minidump_stackwalk` built from a full Chromium source checkout — out of reach of this project's minimal-CEF-SDK CI setup, not attempted. Version-update automation and sandbox verification remain not started. |
 
 ## Appendix A.1 checklist (live)
 
 ```text
-[ ] Process architecture understood/documented   (real, working, CI-proven — but no dedicated primer doc yet)
-[ ] Message loop decision documented              (same — code + test, no dedicated doc yet)
-[ ] Thread affinity documented                    (same — same caveat)
-[ ] CEF reference-count/lifetime rules documented (same — same caveat)
+[x] Process architecture understood/documented   — PR #390, docs/cef/knowledge/cef-architecture-primer.md's "Process model" section (real, CI-proven, PR #388 evidence)
+[x] Message loop decision documented              — PR #390, cef-architecture-primer.md's "Message-loop choice and why" section
+[x] Thread affinity documented                    — PR #390, docs/cef/knowledge/threading-and-lifetimes.md's "Thread map" section (UI-thread callbacks only; IO thread and render-process-side code remain untouched)
+[x] CEF reference-count/lifetime rules documented — PR #390, threading-and-lifetimes.md (IMPLEMENT_REFCOUNTING/CefRefPtr usage + a real callback-lifetime bug found and fixed)
 [ ] Rust binding unsafe surface reviewed          (trivial surface so far, not representative)
 [ ] Binding API gaps catalogued
 [x] Unpackaged CEF resource layout proven          — PR #388, real filesystem listing in CI (real shipped/installer packaging remains separate, unproven, later scope)
@@ -53,11 +53,11 @@ CI validation of this block ("fail CI when a required item for the active progra
 ## CEF competency gate (roadmap §4.11.6, blocks `WS-CEF-IPC`)
 
 ```text
-[ ] CEF process architecture documented            (no dedicated primer doc yet — see domains table)
+[x] CEF process architecture documented            — PR #390, docs/cef/knowledge/cef-architecture-primer.md (sandbox expectations still unproven — see domains table)
 [x] chosen Rust/C++ integration model documented   — docs/adr/0020-cef-binding-choice-thin-cpp-host.md
 [x] binding version pinned                         — scripts/cef/cef-version.json
 [x] unsafe/FFI boundary identified                 — apps/desktop-cef/rust-core/, proven in CI (PR #388)
-[ ] threading/lifetime map reviewed                 (no dedicated doc yet — see domains table)
+[x] threading/lifetime map reviewed                 — PR #390, docs/cef/knowledge/threading-and-lifetimes.md (IO thread/async-cancellation still untouched — see domains table)
 [x] clean repeated startup/shutdown proven          — PR #388, 3/3 cycles, cef-learning-harness CI job
 [x] renderer termination observed and handled       — PR #392, chrome://crash deliberately crashes the renderer, OnRenderProcessTerminated fires, browser process/message loop survive, cef-learning-harness CI job
 [ ] sandbox development plan validated
@@ -67,7 +67,7 @@ CI validation of this block ("fail CI when a required item for the active progra
 [ ] upgrade playbook exists
 ```
 
-This gate is **not** satisfied yet — 6 of 12 items checked, several with explicit caveats above. `WS-CEF-IPC` (Wave 4) remains blocked.
+This gate is **not** satisfied yet — 8 of 12 items checked, several with explicit caveats above. `WS-CEF-IPC` (Wave 4) remains blocked.
 
 ## What this snapshot (Wave 2, 2026-08-18/19) does NOT claim
 
@@ -76,7 +76,7 @@ Superseding the original "Wave 0 does not claim" list, now that some of those it
 - The CEF integration approach **has** been selected (Option B, ADR-0020) — this is no longer an open item.
 - A learning harness **does** exist and runs in CI (`cef-learning-harness`, PR #388) — this is no longer an open item.
 - Still true: no external-expertise engagement has been triggered — none of the escalation criteria (roadmap §4.11.5) have occurred.
-- Still true, and still the most important caveat: this is Linux-only, one GPU config per machine, `no_sandbox=true` throughout, no accessibility/crash-symbolization work, and no dedicated architecture/threading/binding-cookbook prose docs exist yet even where the underlying code+test evidence is real. The competency gate above is explicitly **not** satisfied.
+- Still true, and still the most important caveat: this is Linux-only (X11 proven since PR #388, Wayland smoke also proven PR #393 — but one virtual CI runner, no real GPU/hardware matrix), `no_sandbox=true` throughout, no dump symbolization (crash *reporting* is proven), no working accessibility mechanism (a real CEF-151 API blocker was found and documented, not silently skipped), and no upgrade-playbook prose exists yet (`docs/cef/knowledge/binding-upgrade-playbook.md` remains a skeleton — architecture, threading, and binding-cookbook docs are no longer skeletons, PR #390). The competency gate above is explicitly **not** satisfied.
 - This matrix will continue to be updated in place as each item is genuinely satisfied, with a link to the proving test/CI job/doc (roadmap §61.1.4 evidence-link pattern) — not marked done on intention alone.
 
 ## Update discipline

@@ -56,7 +56,7 @@ documents:
       - cef-learning-harness
       # cef-competency-gate: no such CI workflow/job exists yet — planned, not implemented (CodeRabbit review finding on PR #389). Re-add once it's a real job.
     driftCheckTool: "planned — not implemented, see Wave 1"
-    note: "Updated in place for Wave 2 (PR #386/#387/#388/#391/#392/#393) — 3 of 7 cef_competency items now true with linked evidence (renderer_crash_ci added, PR #392); Wayland smoke checked in Appendix A.1 (PR #393, no dedicated cef_competency field for it per the roadmap's own §61.1.3 shape); competency gate still not satisfied (6/12)."
+    note: "Updated in place for Wave 2 (PR #386/#387/#388/#391/#392/#393) — 4 of 7 cef_competency items now true with linked evidence (lifetime_model_reviewed and renderer_crash_ci added); doc-sync fix flipped 2 more Appendix A.1/gate items to checked once cef-architecture-primer.md/threading-and-lifetimes.md were noticed to already have real content from PR #390 (previously left unchecked on a stale 'no dedicated doc yet' annotation); Wayland smoke checked in Appendix A.1 (PR #393, no dedicated cef_competency field for it per the roadmap's own §61.1.3 shape); competency gate still not satisfied (8/12)."
 
   - path: docs/cef/TAURI-COUPLING-INVENTORY.md
     tier: B

@@ -1,11 +1,11 @@
 # CEF/Binding Upgrade Playbook
 
-**Status:** Not started — no CEF integration exists yet in this repository. No binding or CEF version has been selected.
+**Status:** Not started — this playbook's own prose is unwritten because no CEF/Chromium version upgrade has ever happened yet in this repository. CEF integration itself is real (`apps/desktop-cef/`, ADR-0020), and a version is pinned (`scripts/cef/cef-version.json`, currently `151.3.18+gbeff58d+chromium-151.0.7922.138`) — this doc will get real content the first time that pin actually moves.
 **Scope:** The repeatable procedure for upgrading the pinned CEF/Chromium version and/or the Rust binding crate version — what to re-validate, what evidence to collect, and how the competency-regression policy (roadmap §61.1.6) applies.
 **Tier:** A (release/security-critical) — see [`../OWNERSHIP.yaml`](../OWNERSHIP.yaml).
 **Roadmap context:** [`../ROADMAP-CEF-DESKTOP-MIGRATION.md`](../ROADMAP-CEF-DESKTOP-MIGRATION.md) §34 (CEF version governance), §34.1 (security patch SLA), §44.4 (compatibility-floor gate), §61.1.6 (competency regression policy).
 
-## Outline (to be filled in once a first CEF version is pinned, Wave 2)
+## Outline (to be filled in once a first CEF version upgrade actually happens)
 
 - Routine upgrade checklist: did Linux runtime dependencies change? did the distro/glibc floor move? did Wayland/X11 behavior change? did sandbox requirements change? did packaged resource layout change? (§44.4)
 - Emergency security-patch upgrade path — shortened validation, but never skipping signature verification, sandbox smoke, startup, project open/save, updater correctness, basic a11y/focus, migration compatibility (§34.1.2)

@@ -1,6 +1,6 @@
 # CEF Debugging and Crash Playbook
 
-**Status:** Not started — no CEF integration exists yet in this repository.
+**Status:** Not started — this playbook's own prose (process-role crash taxonomy, symbolization procedure, hang detection) is still Wave 3+ scope. CEF integration itself is real, and crash *reporting* (the raw material for a future symbolization section) is now proven in CI — see `docs/cef/knowledge/cef-architecture-primer.md`'s "Crash reporting" section (PR #392) for what currently exists: `crash_reporter.cfg`, `CefCrashReportingEnabled()`, a deliberately induced renderer crash producing a real Crashpad `.dmp`. Decoding that dump (`dump_syms`/`minidump_stackwalk`) needs a full Chromium source checkout and remains unattempted.
 **Scope:** How to diagnose CEF-specific failures in WorldScript's build — process-role crash classification (native host / browser / renderer / GPU / hang-without-crash), symbolization procedure, minidump handling, GPU/Wayland/X11 troubleshooting, and the operational Crash Ops subsystem's actual behavior.
 **Tier:** A (release/security-critical) — see [`../OWNERSHIP.yaml`](../OWNERSHIP.yaml).
 **Roadmap context:** [`../ROADMAP-CEF-DESKTOP-MIGRATION.md`](../ROADMAP-CEF-DESKTOP-MIGRATION.md) §41.1–§41.5 (Crash Operations), Appendix A.5 (crash/update ops checklist), Appendix D (process attribution schema).