detached 813f329

docs: remove internal CEF cache and first-presentation notes (#434)

commit
813f3291519041d19489b5070482f0a9b588b782
author
bnema · · 2026-09-12 13:06 UTC
committer
GitHub · · 2026-09-12 13:06 UTC
parent
cfb8766
signature
GPG UnverifiedB5690EEEBB952194 The key is unknown
3 files · +1 -166
D docs/cef-cache-contract.md +0 -50
@@ -1,50 +0,0 @@
1-# CEF cache contract
2-
3-Current product behavior for the CEF engine. No configuration change is
4-proposed here; setting an explicit `CachePath` requires the P3.3
5-compatibility decision with data-preservation tests and approval.
6-
7-## Configured settings
8-
9-- `RootCachePath` is set to the resolved state root (`DUMBER_CEF_ROOT_CACHE_PATH`
10- override, engine cache dir, data dir, or profile default, in that order).
11-- `CachePath` is intentionally left empty: with an empty `CachePath` CEF runs
12- the global request context incognito-style, with in-memory-only storage.
13- `RootCachePath` does NOT implicitly supply `CachePath` and does not grant
14- persistent `localStorage`: HTML5 storage only persists across sessions with
15- a non-empty `CachePath`. Locked by
16- `TestPrepareCEFSettings_LeavesCachePathToCEFDefault`.
17-- Browsers are created with a nil request context (`factory.go`), so every
18- window shares the global request context and its storage. No per-window
19- isolation is claimed.
20-
21-## Observed behavior
22-
23-Orderly-restart runs once suggested HTTP asset reuse and localStorage
24-persistence across restarts with this configuration, but that observation is
25-unverified against CEF semantics: with an empty `CachePath` the global
26-context is incognito-style and profile data (including `localStorage`) is
27-expected to be memory-only, so restart persistence must NOT be assumed. The
28-seed/read-only probes below are the only accepted proof; until they run
29-green on a display host, treat this configuration as non-persistent.
30-Setting an explicit `CachePath` under `RootCachePath` requires the P3.3
31-compatibility decision with data-preservation tests and approval.
32-
33-## Display-side verification (pending)
34-
35-The binding exposes everything the probe needs; no new API is required:
36-
37-1. `RequestContextGetGlobalContext()` plus
38- `BrowserHost.GetRequestContext()` identity comparison proves windows
39- share the global context.
40-2. `RequestContext.GetCachePath()` equality/containment against the
41- configured state root proves the effective on-disk location. Export
42- only equality and persistence assertions, never paths.
43-3. Seed/read-only probes: seed cacheable assets, localStorage, and
44- synthetic cookies at a stable fixture origin, restart orderly, and read
45- before any reseeding. Distinct-profile probes also read before writing.
46- Include a no-store control and distinguish no-request hits from
47- conditional revalidation. Assert no non-fixture destination is
48- contacted (favicon-provider egress control included).
49-4. Never infer storage behavior from forcibly killed helpers; always shut
50- down gracefully and let CEF stop its helpers.
@@ -1,50 +0,0 @@
1-# CEF cache contract
2-
3-Current product behavior for the CEF engine. No configuration change is
4-proposed here; setting an explicit `CachePath` requires the P3.3
5-compatibility decision with data-preservation tests and approval.
6-
7-## Configured settings
8-
9-- `RootCachePath` is set to the resolved state root (`DUMBER_CEF_ROOT_CACHE_PATH`
10- override, engine cache dir, data dir, or profile default, in that order).
11-- `CachePath` is intentionally left empty: with an empty `CachePath` CEF runs
12- the global request context incognito-style, with in-memory-only storage.
13- `RootCachePath` does NOT implicitly supply `CachePath` and does not grant
14- persistent `localStorage`: HTML5 storage only persists across sessions with
15- a non-empty `CachePath`. Locked by
16- `TestPrepareCEFSettings_LeavesCachePathToCEFDefault`.
17-- Browsers are created with a nil request context (`factory.go`), so every
18- window shares the global request context and its storage. No per-window
19- isolation is claimed.
20-
21-## Observed behavior
22-
23-Orderly-restart runs once suggested HTTP asset reuse and localStorage
24-persistence across restarts with this configuration, but that observation is
25-unverified against CEF semantics: with an empty `CachePath` the global
26-context is incognito-style and profile data (including `localStorage`) is
27-expected to be memory-only, so restart persistence must NOT be assumed. The
28-seed/read-only probes below are the only accepted proof; until they run
29-green on a display host, treat this configuration as non-persistent.
30-Setting an explicit `CachePath` under `RootCachePath` requires the P3.3
31-compatibility decision with data-preservation tests and approval.
32-
33-## Display-side verification (pending)
34-
35-The binding exposes everything the probe needs; no new API is required:
36-
37-1. `RequestContextGetGlobalContext()` plus
38- `BrowserHost.GetRequestContext()` identity comparison proves windows
39- share the global context.
40-2. `RequestContext.GetCachePath()` equality/containment against the
41- configured state root proves the effective on-disk location. Export
42- only equality and persistence assertions, never paths.
43-3. Seed/read-only probes: seed cacheable assets, localStorage, and
44- synthetic cookies at a stable fixture origin, restart orderly, and read
45- before any reseeding. Distinct-profile probes also read before writing.
46- Include a no-store control and distinguish no-request hits from
47- conditional revalidation. Assert no non-fixture destination is
48- contacted (favicon-provider egress control included).
49-4. Never infer storage behavior from forcibly killed helpers; always shut
50- down gracefully and let CEF stop its helpers.
D docs/first-presentation.md +0 -114
@@ -1,114 +0,0 @@
1-# CEF accelerated first-presentation startup trace
2-
3-Dumber records this cold-start timeline **only for the accelerated CEF → DMABUF
4-→ GTK path**. It is not a backend-neutral startup metric: the WebKit backend
5-does not add milestones to this trace and never emits this CEF summary.
6-
7-For a selected CEF GUI process, Dumber captures neutral `process_entry` and
8-`config_complete` timestamps, then activates and seeds this CEF-owned trace only
9-after configuration selects CEF. CEF helper processes, WebKit GUI startup, the
10-standalone omnibox, and CLI commands never initialize this trace, record its
11-milestones, or emit its summary. A selected CEF GUI trace accepts these one-shot
12-milestones only in order:
13-
14-1. `process_entry`
15-2. `config_complete`
16-3. `cef_library_load_begin` (immediately before `InitWithApp`)
17-4. `cef_initialized`
18-5. `browser_create_requested`
19-6. `first_accelerated_paint_received`
20-7. `first_dmabuf_texture_swap` (after `GtkPicture.SetPaintable` succeeds)
21-8. `first_gtk_presentation` (the subsequent GTK frame-clock after-paint)
22-
23-The CEF-to-GTK bridge owns the native accelerated-paint, DMABUF texture-swap,
24-and GTK presentation boundaries. Dumber records the bridge's ordered callbacks;
25-it does not synthesize them for another engine or rendering path. CEF
26-library-load completion is intentionally not recorded: `InitWithApp` is an
27-opaque operation. Duplicate, unknown, and out-of-order transitions are
28-rejected. At the last milestone Dumber emits exactly one normal-level JSON
29-summary (`startup_trace: first presentation`) with the selected CEF render
30-backend, an `incomplete_reason`, total milliseconds, and monotonic milestones.
31-
32-A non-DMABUF CEF backend or a missing accelerated callback does not produce a
33-complete summary and is not comparable with this measurement. In particular,
34-WebKit startup must be measured with a separately defined WebKit-specific
35-contract rather than this CEF trace.
36-
37-## Reproducible collection
38-
39-Build the candidate and its build manifest, then run:
40-
41-```bash
42-DUMBER_CEF_DIR=/path/to/selected-cef-runtime \
43-DUMBER_FIRST_PRESENTATION_BIN="$PWD/dist/dumber" \
44-DUMBER_BUILD_MANIFEST="$PWD/dist/dumber.manifest.json" \
45-DUMBER_MACHINE_GPU_PROFILE=integrated-gpu \
46- scripts/collect_first_presentation.sh
47-```
48-
49-The manifest records the measured binary SHA-256, the 40-character source
50-revision, and the selected `github.com/bnema/purego-cef2gtk` version plus its
51-full 40-character revision. Generate it at build time from the same tree
52-that produced the binary; collection verifies the manifest against
53-`go version -m` output for the measured binary and fails closed on missing
54-or mismatched attribution.
55-
56-```bash
57-make build-manifest
58-# or, equivalently:
59-python3 scripts/generate_build_manifest.py --binary dist/dumber
60-```
61-
62-Manifest schema (JSON, sorted keys):
63-
64-```json
65-{
66- "binary_sha256": "<hex sha256 of the measured binary>",
67- "source_revision": "<40-hex git revision of the built source>",
68- "modules": {
69- "github.com/bnema/purego-cef2gtk": {
70- "version": "<exact version from go version -m>",
71- "revision": "<40-hex git hash from go mod download origin>"
72- }
73- }
74-}
75-```
76-
77-The generator refuses binaries built with a `replace` directive, non-tag
78-dependency versions, and missing source revisions. The default manifest
79-path is `<binary>.manifest.json`, which is also the collector default
80-(`DUMBER_BUILD_MANIFEST` overrides it).
81-
82-The collector is for the accelerated CEF/DMABUF/GTK contract above. By default
83-each collection is a fresh directory below
84-`$XDG_STATE_HOME/dumber/roadmap-evidence` (or
85-`$HOME/.local/state/dumber/roadmap-evidence` when `XDG_STATE_HOME` is unset),
86-not in the repository. `DUMBER_FIRST_PRESENTATION_OUTPUT` may override it only
87-with a new absolute directory below an existing non-symlink parent. The
88-collector never clears or reuses a caller-supplied path.
89-
90-The script requires the current display and an explicit `DUMBER_CEF_DIR`
91-selecting the measured runtime; there is no default path or version.
92-`scripts/cef_runtime_probe.py` runs in a separate bounded subprocess, opens
93-only the selected `libcef.so` with standard-library ctypes, calls the
94-header-verified `cef_version_info(int)` entries (0-7), and reports numeric
95-version fields plus the library hash, never its path. The candidate must still
96-pass its normal loader ABI/version validation; the probe never bypasses it.
97-Runtimes below Chrome major 150 fail collection. It performs
98-exactly five bounded launches with fresh XDG homes and CEF root cache, fixes the
99-DMABUF/Vulkan renderer, and writes exactly `metadata.json`, `run-01.json`
100-through `run-05.json`, and `baseline.json`. Metadata includes only coarse,
101-comparison-safe OS/architecture, display protocol, and machine/GPU profile
102-labels. Set `DUMBER_MACHINE_GPU_PROFILE` to one of `generic-gpu`,
103-`integrated-gpu`, `discrete-gpu`, `hybrid-gpu`, `virtual-gpu`, or `unknown-gpu`;
104-do not use a device model or other identifier. Publish only the seven reviewed
105-JSON files to an external Gist. Raw logs and temporary XDG homes are removed and
106-must not be published. `metadata.json` binds the measured binary SHA-256 to
107-its source revision via `go version -m` plus the build manifest, and records
108-the selected `github.com/bnema/purego-cef2gtk` version, tag, and full revision
109-from that same binary-bound evidence; it never derives provenance from the
110-collection checkout. The child processes receive exactly the selected runtime
111-via `CEF_DIR`, never a conflicting inherited override. Branch selectors,
112-replacement contamination, version/manifest mismatches, or a missing manifest
113-fail collection. A missing or incomplete timeline, non-DMABUF backend, or invalid
114-run also fails collection.
@@ -1,114 +0,0 @@
1-# CEF accelerated first-presentation startup trace
2-
3-Dumber records this cold-start timeline **only for the accelerated CEF → DMABUF
4-→ GTK path**. It is not a backend-neutral startup metric: the WebKit backend
5-does not add milestones to this trace and never emits this CEF summary.
6-
7-For a selected CEF GUI process, Dumber captures neutral `process_entry` and
8-`config_complete` timestamps, then activates and seeds this CEF-owned trace only
9-after configuration selects CEF. CEF helper processes, WebKit GUI startup, the
10-standalone omnibox, and CLI commands never initialize this trace, record its
11-milestones, or emit its summary. A selected CEF GUI trace accepts these one-shot
12-milestones only in order:
13-
14-1. `process_entry`
15-2. `config_complete`
16-3. `cef_library_load_begin` (immediately before `InitWithApp`)
17-4. `cef_initialized`
18-5. `browser_create_requested`
19-6. `first_accelerated_paint_received`
20-7. `first_dmabuf_texture_swap` (after `GtkPicture.SetPaintable` succeeds)
21-8. `first_gtk_presentation` (the subsequent GTK frame-clock after-paint)
22-
23-The CEF-to-GTK bridge owns the native accelerated-paint, DMABUF texture-swap,
24-and GTK presentation boundaries. Dumber records the bridge's ordered callbacks;
25-it does not synthesize them for another engine or rendering path. CEF
26-library-load completion is intentionally not recorded: `InitWithApp` is an
27-opaque operation. Duplicate, unknown, and out-of-order transitions are
28-rejected. At the last milestone Dumber emits exactly one normal-level JSON
29-summary (`startup_trace: first presentation`) with the selected CEF render
30-backend, an `incomplete_reason`, total milliseconds, and monotonic milestones.
31-
32-A non-DMABUF CEF backend or a missing accelerated callback does not produce a
33-complete summary and is not comparable with this measurement. In particular,
34-WebKit startup must be measured with a separately defined WebKit-specific
35-contract rather than this CEF trace.
36-
37-## Reproducible collection
38-
39-Build the candidate and its build manifest, then run:
40-
41-```bash
42-DUMBER_CEF_DIR=/path/to/selected-cef-runtime \
43-DUMBER_FIRST_PRESENTATION_BIN="$PWD/dist/dumber" \
44-DUMBER_BUILD_MANIFEST="$PWD/dist/dumber.manifest.json" \
45-DUMBER_MACHINE_GPU_PROFILE=integrated-gpu \
46- scripts/collect_first_presentation.sh
47-```
48-
49-The manifest records the measured binary SHA-256, the 40-character source
50-revision, and the selected `github.com/bnema/purego-cef2gtk` version plus its
51-full 40-character revision. Generate it at build time from the same tree
52-that produced the binary; collection verifies the manifest against
53-`go version -m` output for the measured binary and fails closed on missing
54-or mismatched attribution.
55-
56-```bash
57-make build-manifest
58-# or, equivalently:
59-python3 scripts/generate_build_manifest.py --binary dist/dumber
60-```
61-
62-Manifest schema (JSON, sorted keys):
63-
64-```json
65-{
66- "binary_sha256": "<hex sha256 of the measured binary>",
67- "source_revision": "<40-hex git revision of the built source>",
68- "modules": {
69- "github.com/bnema/purego-cef2gtk": {
70- "version": "<exact version from go version -m>",
71- "revision": "<40-hex git hash from go mod download origin>"
72- }
73- }
74-}
75-```
76-
77-The generator refuses binaries built with a `replace` directive, non-tag
78-dependency versions, and missing source revisions. The default manifest
79-path is `<binary>.manifest.json`, which is also the collector default
80-(`DUMBER_BUILD_MANIFEST` overrides it).
81-
82-The collector is for the accelerated CEF/DMABUF/GTK contract above. By default
83-each collection is a fresh directory below
84-`$XDG_STATE_HOME/dumber/roadmap-evidence` (or
85-`$HOME/.local/state/dumber/roadmap-evidence` when `XDG_STATE_HOME` is unset),
86-not in the repository. `DUMBER_FIRST_PRESENTATION_OUTPUT` may override it only
87-with a new absolute directory below an existing non-symlink parent. The
88-collector never clears or reuses a caller-supplied path.
89-
90-The script requires the current display and an explicit `DUMBER_CEF_DIR`
91-selecting the measured runtime; there is no default path or version.
92-`scripts/cef_runtime_probe.py` runs in a separate bounded subprocess, opens
93-only the selected `libcef.so` with standard-library ctypes, calls the
94-header-verified `cef_version_info(int)` entries (0-7), and reports numeric
95-version fields plus the library hash, never its path. The candidate must still
96-pass its normal loader ABI/version validation; the probe never bypasses it.
97-Runtimes below Chrome major 150 fail collection. It performs
98-exactly five bounded launches with fresh XDG homes and CEF root cache, fixes the
99-DMABUF/Vulkan renderer, and writes exactly `metadata.json`, `run-01.json`
100-through `run-05.json`, and `baseline.json`. Metadata includes only coarse,
101-comparison-safe OS/architecture, display protocol, and machine/GPU profile
102-labels. Set `DUMBER_MACHINE_GPU_PROFILE` to one of `generic-gpu`,
103-`integrated-gpu`, `discrete-gpu`, `hybrid-gpu`, `virtual-gpu`, or `unknown-gpu`;
104-do not use a device model or other identifier. Publish only the seven reviewed
105-JSON files to an external Gist. Raw logs and temporary XDG homes are removed and
106-must not be published. `metadata.json` binds the measured binary SHA-256 to
107-its source revision via `go version -m` plus the build manifest, and records
108-the selected `github.com/bnema/purego-cef2gtk` version, tag, and full revision
109-from that same binary-bound evidence; it never derives provenance from the
110-collection checkout. The child processes receive exactly the selected runtime
111-via `CEF_DIR`, never a conflicting inherited override. Branch selectors,
112-replacement contamination, version/manifest mismatches, or a missing manifest
113-fail collection. A missing or incomplete timeline, non-DMABUF backend, or invalid
114-run also fails collection.
M internal/infrastructure/cef/engine_init_test.go +1 -2
@@ -67,8 +67,7 @@ func TestPrepareCEFSettings_UsesResolvedProfilePaths(t *testing.T) {
6767 // the global request context runs incognito-style with in-memory storage.
6868 // RootCachePath does not supply CachePath and grants no persistent
6969 // localStorage. Setting an explicit CachePath requires the P3.3
70-// compatibility decision with data-preservation tests; see
71-// docs/cef-cache-contract.md.
70+// compatibility decision with data-preservation tests.
7271 func TestPrepareCEFSettings_LeavesCachePathToCEFDefault(t *testing.T) {
7372 logger := zerolog.Nop()
7473 profile := testCEFDevProfile(t)
@@ -67,8 +67,7 @@ func TestPrepareCEFSettings_UsesResolvedProfilePaths(t *testing.T) {
67 // the global request context runs incognito-style with in-memory storage.67 // the global request context runs incognito-style with in-memory storage.
68 // RootCachePath does not supply CachePath and grants no persistent68 // RootCachePath does not supply CachePath and grants no persistent
69 // localStorage. Setting an explicit CachePath requires the P3.369 // localStorage. Setting an explicit CachePath requires the P3.3
70-// compatibility decision with data-preservation tests; see70+// compatibility decision with data-preservation tests.
71-// docs/cef-cache-contract.md.
72 func TestPrepareCEFSettings_LeavesCachePathToCEFDefault(t *testing.T) {71 func TestPrepareCEFSettings_LeavesCachePathToCEFDefault(t *testing.T) {
73 logger := zerolog.Nop()72 logger := zerolog.Nop()
74 profile := testCEFDevProfile(t)73 profile := testCEFDevProfile(t)

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 8

Tags 42

↑↓ moveenter openesc close