Skip to content

docs(cef): flip Wave 2 evidence from spike-only to real, CI-run (PR #388) #389

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
qnbs merged 2 commits into from
Aug 18, 2026
Merged

docs(cef): flip Wave 2 evidence from spike-only to real, CI-run (PR #388) #389

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1472e55
docs(cef): flip Wave 2 evidence from spike-only to real, CI-run (PR #…
qnbs Aug 18, 2026
916a20a
fix(docs): correct 4 overclaims in the Wave 2 evidence-flip PR
qnbs Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions docs/architecture/native-readiness.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,11 +57,13 @@ Wave 2's first deliverable — the CEF binding/C++ decision — is now backed by
| 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. |
| CEF SDK fetch/verify + version diagnostics automated | **PASS** | cef-runtime | `🧪 CEF Learning Harness` CI job (`.github/workflows/cef-learning-harness.yml`) fetches the pinned CEF SDK, verifies its checksum, and parses real version macros out of the extracted `include/cef_version.h` — a genuine CI-run check, not a doc claim. Does not build or run the CEF host itself yet (see ADR-0020 Consequences for that follow-up). |
| CEF renders reliably on Linux dev systems | DEBT — partial | cef-runtime, Wave 2 (in progress) | Two data points now (dev-machine spike + CI-run PR #388 on GitHub Actions `ubuntu-latest`), the second of which renders the **real production bundle** (not `about:blank`) with a verified exact title, not just a blank page. Still one GPU config per machine, no sandbox, X11/Xvfb only. 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 | **PASS** | cef-runtime | `docs/cef/knowledge/subprocess-and-shutdown.md`'s core Wave 2 claim (SIGTERM → graceful `TryCloseBrowser`/`OnBeforeClose`/`CefQuitMessageLoop`/`CefShutdown`, repeated clean start/close cycles) now has a real linked chain: test (`scripts/cef/run-launch-cycle-proof.mjs`) → CI job (`🧪 CEF Learning Harness`) → doc, exactly what §61.1.4 requires. Save-coordinator/window-state persistence remain explicitly Wave 5+ scope (not a Wave 2 gap); Windows/macOS and a real packaged layout remain open, tracked in the doc's own "Outline" section. |
| Early Accessibility Gate | Not yet attempted | cef-runtime, Wave 2 | Out of this proof's scope entirely — no accessibility tree/API integration was touched. |
| Sandbox posture | Not yet attempted | desktop-security, Wave 2/3 (roadmap §12) | Every run so far used `no_sandbox=true`; zero evidence either way on this row. |
| CEF SDK fetch/verify + version diagnostics automated | **PASS** | cef-runtime | `🧪 CEF Learning Harness` CI job (`.github/workflows/cef-learning-harness.yml`) fetches the pinned CEF SDK, verifies its checksum, and parses real version macros out of the extracted `include/cef_version.h` — a genuine CI-run check, not a doc claim. |
| Linux dependency inventory — clean-machine data point | DEBT — partial | cef-runtime | Same CI job runs the package-presence check against a stock `ubuntu-latest` runner before any `apt-get`, adding a real second data point beyond the spike's one already-configured dev machine. Still narrow: `dpkg` package-presence only (not `ldd` against the actual shipped `.so` files), one distro/runner image. |
| CEF host build + repeated launch/close cycle proof, in CI | **PASS** | cef-runtime | PR #388: `apps/desktop-cef/`'s `worldscript_host` (real, repo-committed C++/Rust source, not spike code) builds against the fetched CEF SDK and runs 3 independently-verified clean start/close cycles under Xvfb in CI — the roadmap's literal "isolated learning harness" / "safe repeated startup/shutdown" deliverables (§3142), not just the fetch/diagnostics increment. |
| Rust FFI boundary proven inside the real host | **PASS** | cef-runtime, rust-core | `worldscript_rust_ping()` (rust-core, linked via Corrosion) is called from `OnAfterCreated` on every cycle and its exact sentinel value observed in CI output — stronger than the ADR-0020 spike's decoupled isolation test, since this proves the boundary works inside the actual multi-process CEF host, not a standalone C++ program. |

**Overall for this snapshot**: 2 PASS, 3 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.
**Overall for this snapshot**: 5 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.
67 changes: 37 additions & 30 deletions docs/cef/CEF-RUST-COMPETENCY-MATRIX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,76 +1,83 @@
# CEF/Rust Competency Matrix

**Companion to:** [`ROADMAP-CEF-DESKTOP-MIGRATION.md`](ROADMAP-CEF-DESKTOP-MIGRATION.md) §4.11, §61.1, Appendix A.1 · [ADR-0019](../adr/0019-cef-desktop-runtime-strategy.md)
**Established:** Wave 0, 2026-08-18. **Baseline: nothing below is done yet.** No CEF code, dependency, or integration exists in this repository as of this commit — every item is honestly `false`/not-started. This file exists so future waves have a live, gradeable target instead of re-deriving the checklist from the roadmap prose each time.
**Established:** Wave 0, 2026-08-18. **Baseline was: nothing done yet.** Updated in place, 2026-08-18/19 (Wave 2, ADR-0020 spike + PR #386/#387/#388), per this doc's own "Update discipline" below — items flip to `true` only with a linked evidence commit, in the same commit as the flip. This file exists so future waves have a live, gradeable target instead of re-deriving the checklist from the roadmap prose each time.

This is an engineering gate (roadmap §4.11.6), not a training checklist. `WS-CEF-IPC` (Wave 4) and any production storage capability exposing privileged native operations may not proceed until the relevant items below are `true` with linked evidence.

## Machine-readable manifest (roadmap §61.1.3 shape)

```yaml
cef_competency:
binding_model_documented: false
binding_model_documented: true # docs/adr/0020-cef-binding-choice-thin-cpp-host.md
lifetime_model_reviewed: false
repeated_shutdown_ci: false
repeated_shutdown_ci: true # scripts/cef/run-launch-cycle-proof.mjs, cef-learning-harness CI job (PR #388)
renderer_crash_ci: false
sandbox_smoke: false
accessibility_smoke: false
crash_symbolization_smoke: false
```

CI validation of this block ("fail CI when a required item for the active program phase is absent or false") is not yet implemented — this manifest is hand-maintained for now, matching every `driftCheckTool: "planned — not implemented"` entry in `OWNERSHIP.yaml`.

## Required competency domains (roadmap §4.11.1)

| Domain | Status | Evidence |
|---|---|---|
| CEF architecture (process model, browser/frame/client ownership, message loop, shutdown ordering, subprocess packaging, sandbox expectations) | Not started | — |
| CEF threading & lifetime rules (UI-thread callbacks, IO thread, ref-counted objects, callback lifetime, async cancellation, shutdown races) | Not started | — |
| Rust binding layer (crate/version, unsafe/FFI boundary, wrapper ownership, API coverage gaps, upgrade procedure) | Not started | — |
| Cross-platform native host (Linux loader/resource layout, Windows process/installer/sandbox, macOS bundle/signing, window lifecycle, high-DPI, IME/a11y) | Not started | — |
| Operational CEF (crash reporting, symbol handling, version-update automation, sandbox verification, packaging deps, runtime diagnostics) | Not started | — |
| 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. |
| 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, symbol handling, version-update automation, and sandbox verification all remain not started. |

## Appendix A.1 checklist (live)

```text
[ ] Process architecture understood/documented
[ ] Message loop decision documented
[ ] Thread affinity documented
[ ] CEF reference-count/lifetime rules documented
[ ] Rust binding unsafe surface reviewed
[ ] 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)
[ ] Rust binding unsafe surface reviewed (trivial surface so far, not representative)
[ ] Binding API gaps catalogued
[ ] Subprocess packaging proven
[ ] Repeated startup/shutdown harness green
[x] Unpackaged CEF resource layout proven — PR #388, real filesystem listing in CI (real shipped/installer packaging remains separate, unproven, later scope)
[x] Repeated startup/shutdown harness green — PR #388, 3/3 cycles, cef-learning-harness CI job
[ ] Renderer crash observation green
[ ] Accessibility smoke green
[ ] Crash-reporting/symbolization smoke green
[ ] Linux dependency inventory complete
[ ] X11/Wayland initial smoke complete
[ ] Linux dependency inventory complete (inventoried, not yet proven sufficient — see native-readiness.md)
[ ] X11/Wayland initial smoke complete (X11 only; Wayland zero evidence)
[ ] Upgrade playbook written
[ ] External-expertise escalation path documented
```

## CEF competency gate (roadmap §4.11.6, blocks `WS-CEF-IPC`)

```text
[ ] CEF process architecture documented
[ ] chosen Rust/C++ integration model documented
[ ] binding version pinned
[ ] unsafe/FFI boundary identified
[ ] threading/lifetime map reviewed
[ ] clean repeated startup/shutdown proven
[ ] renderer termination observed and handled
[ ] CEF process architecture documented (no dedicated primer doc yet — 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] clean repeated startup/shutdown proven — PR #388, 3/3 cycles, cef-learning-harness CI job
[ ] renderer termination observed and handled (not proven — PR #388 exercised normal shutdown only; no test deliberately terminates/crashes a renderer, per Qodo review finding on PR #389)
[ ] sandbox development plan validated
[ ] Linux runtime dependencies inventoried
[ ] Linux runtime dependencies inventoried (inventoried but not yet proven sufficient — see native-readiness.md)
[ ] at least one accessibility smoke test performed
[ ] at least one crash-reporting/symbolization path proven
[ ] upgrade playbook exists
```

## What Wave 0 does NOT claim
This gate is **not** satisfied yet — 4 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

Superseding the original "Wave 0 does not claim" list, now that some of those items are no longer true:

- No CEF integration approach has been selected (roadmap §10, Appendix H scorecard — Wave 2).
- No learning harness exists yet (roadmap §4.11.3, §61.1 — Wave 2).
- No external-expertise engagement has been triggered — none of the escalation criteria (roadmap §4.11.5) have occurred, since no CEF work has started.
- This matrix will 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.
- 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.
- 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

Expand Down
11 changes: 6 additions & 5 deletions docs/cef/OWNERSHIP.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,13 @@ documents:
backup_role: rust-core
last_verified:
worldscript: "v1.27.1"
cef: "not applicable — pre-CEF-selection"
cef: "151.3.18+gbeff58d+chromium-151.0.7922.138"
review_days: 90
related_ci:
- cef-learning-harness
- cef-competency-gate
# 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) — 2 of 7 cef_competency items now true with linked evidence; competency gate still not satisfied (5/12)."

- path: docs/cef/TAURI-COUPLING-INVENTORY.md
tier: B
Expand Down Expand Up @@ -122,7 +123,7 @@ documents:
review_days: 90
related_ci:
- cef-learning-harness
- cef-competency-gate
# 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: "Skeleton only — Status: Not started"

Expand All @@ -137,7 +138,7 @@ documents:
related_ci:
- cef-learning-harness
driftCheckTool: "planned — not implemented, see Wave 1"
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."
note: "Real, CI-run evidence (PR #388) — test (scripts/cef/run-launch-cycle-proof.mjs) -> CI job (cef-learning-harness) -> doc, per §61.1.4. Save-coordinator/window-state steps remain unimplemented Wave 5+ scope."

- path: docs/cef/knowledge/linux-runtime-notes.md
tier: A
Expand All @@ -150,7 +151,7 @@ documents:
related_ci:
- cef-learning-harness
driftCheckTool: "planned — not implemented, see Wave 1"
note: "Preliminary spike evidence only (ADR-0020) — one machine, one GPU, X11 only; not a compatibility contract yet. The package-presence portion of the dependency inventory now also has a real CI-run data point via the cef-learning-harness job (stock ubuntu-latest, pre-apt-get)."
note: "Dev-machine spike (ADR-0020) plus real CI-run evidence (PR #388, GitHub Actions ubuntu-latest) — two machines now, one GPU config each, X11 only; not a compatibility contract yet."

- path: docs/cef/knowledge/debugging-and-crash-playbook.md
tier: A
Expand Down
Loading
Loading