From 8181d40db646a9f9532fd8619758e904618f3abf Mon Sep 17 00:00:00 2001 From: qnbs <155236708+qnbs@users.noreply.github.com> Date: Wed, 19 Aug 2026 07:10:57 +0200 Subject: [PATCH] docs(cef): sync competency matrix to docs already filled in by PR #390 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Real doc-truth drift found while continuing Wave 2 work: 4 checklist items (2 in Appendix A.1, 2 in the CEF competency gate) were still marked unchecked with a "no dedicated doc yet" annotation, but cef-architecture-primer.md and threading-and-lifetimes.md were both filled in with real content back in PR #390 — the checklist was never updated to reflect it. Checks all 4 with evidence links, flips the embedded YAML's lifetime_model_reviewed to true (its own prose counterpart was already checked), and corrects the domains table's "still skeleton" claims for both docs. Gate count corrected from 6/12 to 8/12; cef_competency from 3/7 to 4/7. Also fixes two other stale "no CEF integration exists yet in this repository" claims (binding-upgrade-playbook.md, debugging-and-crash-playbook.md) — both predate this repo's actual CEF integration and were never updated; corrected to state accurately what exists (a pinned CEF version, real crash-reporting groundwork) versus what's genuinely still unwritten (this playbook's own prose, in both cases, pending a real upgrade / Wave 3+ respectively). Co-Authored-By: Claude Sonnet 5 --- docs/cef/CEF-RUST-COMPETENCY-MATRIX.md | 22 +++++++++---------- docs/cef/OWNERSHIP.yaml | 2 +- .../cef/knowledge/binding-upgrade-playbook.md | 4 ++-- .../knowledge/debugging-and-crash-playbook.md | 2 +- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/cef/CEF-RUST-COMPETENCY-MATRIX.md b/docs/cef/CEF-RUST-COMPETENCY-MATRIX.md index d936c0f9..0327b1e7 100644 --- a/docs/cef/CEF-RUST-COMPETENCY-MATRIX.md +++ b/docs/cef/CEF-RUST-COMPETENCY-MATRIX.md @@ -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,8 +24,8 @@ 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. | @@ -33,10 +33,10 @@ CI validation of this block ("fail CI when a required item for the active progra ## 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 diff --git a/docs/cef/OWNERSHIP.yaml b/docs/cef/OWNERSHIP.yaml index 269ce2e9..0d5b3f82 100644 --- a/docs/cef/OWNERSHIP.yaml +++ b/docs/cef/OWNERSHIP.yaml @@ -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 diff --git a/docs/cef/knowledge/binding-upgrade-playbook.md b/docs/cef/knowledge/binding-upgrade-playbook.md index 85a97b6d..d09f5382 100644 --- a/docs/cef/knowledge/binding-upgrade-playbook.md +++ b/docs/cef/knowledge/binding-upgrade-playbook.md @@ -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) diff --git a/docs/cef/knowledge/debugging-and-crash-playbook.md b/docs/cef/knowledge/debugging-and-crash-playbook.md index ce66e0df..c11a377e 100644 --- a/docs/cef/knowledge/debugging-and-crash-playbook.md +++ b/docs/cef/knowledge/debugging-and-crash-playbook.md @@ -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).