From 18f2d76e97fe7750cb20f23b35f5073161743675 Mon Sep 17 00:00:00 2001 From: metif12 Date: Mon, 5 Oct 2026 15:53:23 +0330 Subject: [PATCH 01/29] webview, buildplan, services: make the Linux suite green, 20 of 44 failing to 44/44 The Linux suite had never been run in this repository; the first run had 20 of 44 test files failing, for three unrelated root causes. services did not compile at all. drop.v named read_dropped_paths_native, which lives in drop_windows.c.v, from platform-neutral code. The handler is now in the file that owns it. webview_linux.c.v had 7 compile errors left by the F0 multi-window work: C function declarations that were never added, struct fields passed as pointers instead of .str, a non-mut win that is assigned, and a contexts field mutated through a non-mut reference. jobs_test.v asserted a Windows-only error string. The assertion now branches on the platform instead of expecting one message everywhere; the Linux assertion was planted red on both lines and then restored. buildplan.app_flags had a windows whose value could not vary with the host, because every branch returned the same thing. It is now host-independent, and buildplan_test.v asserts the whole flag string rather than one flag, because the failure mode was an extra flag that no per-flag assertion could see. Measured: 44/44 in the CI container with -gc none, and 44/44 on Windows. --- buildplan/buildplan.v | 30 +++++++++++++++++------- buildplan/buildplan_test.v | 8 +++++++ services/drop.v | 46 +++++++++++++++++------------------- services/drop_windows.c.v | 37 +++++++++++++++++++++++++---- webview/jobs_test.v | 25 ++++++++++++++++++-- webview/webview_linux.c.v | 48 +++++++++++++++++++++++++++----------- 6 files changed, 141 insertions(+), 53 deletions(-) diff --git a/buildplan/buildplan.v b/buildplan/buildplan.v index cb610aa..f4d0fe6 100644 --- a/buildplan/buildplan.v +++ b/buildplan/buildplan.v @@ -114,21 +114,33 @@ pub fn needs_gc_none(target Target) bool { // nothing from the compiler that is not already in the module tree. That // claim is asserted in `tests/e2e_windows/README.md:41` and is why the // two recipes differ. +// +// **It is a pure function of `target`, and that used to be false.** The `-cc gcc` +// branch was wrapped in `$if windows`, which made `app_flags(.windows)` return +// `[]` when it ran on Linux - so a Windows plan could only ever be checked on a +// Windows machine, which is the exact half-checking `Target` exists to prevent. +// The Linux CI run is what found it (2026-10-05), and it was found by the test +// that was written to catch precisely this. +// +// The `$if` was never load-bearing: the only production caller is +// `recipe(target_for_host(), ...)` (cli/vails.v), which always passes the host's +// own target, so `target == .windows` was already true whenever the `$if` was. +// Removing it changed no real build and made the function honest. `cli_flags` +// below adds its Windows flags with no `$if` at all and always did, which is the +// comparison that made the outlier obvious. pub fn app_flags(target Target) []string { mut out := []string{} if needs_gc_none(target) { out << '-gc' out << 'none' } - $if windows { - if target == .windows { - // `-cc gcc` is two argv entries on purpose: `v` takes them - // as separate words, and joining them into one flag with a - // space is what `quote_if_needed` exists to handle for the - // hand-assembled case, not for this list. - out << '-cc' - out << 'gcc' - } + if target == .windows { + // `-cc gcc` is two argv entries on purpose: `v` takes them + // as separate words, and joining them into one flag with a + // space is what `quote_if_needed` exists to handle for the + // hand-assembled case, not for this list. + out << '-cc' + out << 'gcc' } return out } diff --git a/buildplan/buildplan_test.v b/buildplan/buildplan_test.v index 4c58cb1..b6234bb 100644 --- a/buildplan/buildplan_test.v +++ b/buildplan/buildplan_test.v @@ -16,6 +16,14 @@ fn test_linux_app_builds_with_gc_none() { fn test_windows_app_needs_only_cc_gcc() { // The README asserts an app needs no flags beyond `-cc gcc`; if that // ever stops being true this test is where it should be noticed. + // + // This exact equality is also the guard that caught `app_flags` reading the + // HOST os instead of its `target` argument (2026-10-05, on the first Linux CI + // run): with the branch wrapped in `$if windows` the function returned `[]` + // here on Linux, and an assertion like `f.contains('-cc')` would have passed + // on Windows while checking nothing on Linux. Do not loosen this to `.contains` + // or `.all` — the equality is what makes it a host-independence check, and it + // now runs, and bites, on both platforms. f := app_flags(.windows) assert f == ['-cc', 'gcc'] } diff --git a/services/drop.v b/services/drop.v index f13bbc2..3cf1295 100644 --- a/services/drop.v +++ b/services/drop.v @@ -234,32 +234,30 @@ pub fn drop_files_data(paths []string) string { return '{"paths":[' + items.join(',') + '],"count":' + paths.len.str() + '}' } -// on_drop_message is the handler the window seam calls. A plain function (not a -// closure) so the install site reads the same on every platform. +// ## Where the message handler lives, and why it is not in this file // -// It consumes exactly the messages `decide` says are the drop's, and it reads -// the DROPFILES handle on none other. Reading lParam as an HDROP for a message -// that is not WM_DROPFILES would hand the shell API a pointer to whatever the -// message's lParam happened to be, so `is_drop_message` is asked first and the -// question is not "was it a drop" but "whose handle is this". +// `on_drop_message` used to be here, and it could not be: the one thing it does +// that this file cannot is read an HDROP, and `read_dropped_paths_native` exists +// only in `drop_windows.c.v`. A platform-neutral module may not name a platform +// function at all, so this was not one broken function - it was the whole `services` +// module failing to compile on Linux. // -// A failed emit fails the handler, which the host treats as consumed: a drop the -// frontend never hears about is a drop the user is still holding files for, and -// there is nothing useful to pass on to a window procedure that does not know -// what a DROPFILES handle is. -fn on_drop_message(st &DropState, e webview.HostEvent) !bool { - if decide_drop(e, 0) == .pass_on { - return false - } - // The native read releases the handle as part of reading it, on every path - // including an error - an unreleased HDROP is a shell resource leak per drop, - // and a drop is something a user can do a hundred times an hour. - paths := read_dropped_paths_native(e.lparam) or { - return error('drop: could not read the dropped paths: ' + err.msg()) - } - st.ctx.emit(event_drop_files, drop_files_data(validate_dropped_paths(paths)))! - return true -} +// It lives in `drop_windows.c.v` now, beside its only caller and its only platform +// dependency. `menu_windows.c.v`'s `on_bar_command` is the same arrangement for the +// same reason: a handler that reads a Windows message belongs to that platform's +// backend. +// +// `tray.v` looks like the counter-example and is not. Its `on_host_message` can +// stay neutral because a tray backend *exists on Linux*, so there is a message to +// handle on both sides. The drop service has no Linux half by choice (see +// `drop_linux.c.v`), so a neutral handler would have nothing to be neutral about. +// +// Everything testable stayed here on purpose. `decide_drop`, +// `validate_dropped_paths` and `drop_files_data` are the entire policy, all three +// are pure V, and all three stay covered on both platforms by `drop_test.v`. What +// moved is the one function that needs an HDROP - and so cannot be tested on a +// machine without one, which is the honest reason it was the wrong side of the +// line to begin with. // enable_drop starts accepting drops on this window and installs the seam. // diff --git a/services/drop_windows.c.v b/services/drop_windows.c.v index 85c1702..72fa476 100644 --- a/services/drop_windows.c.v +++ b/services/drop_windows.c.v @@ -86,13 +86,42 @@ const drop_buffer_units = max_dropped_path_len + 1 // An arm with no hook is also what makes `drop.enable` idempotent: the second // call finds the hook present, re-arms the window (harmless - DragAcceptFiles is // a set, not a counter) and returns, rather than stacking a second subclass. +// on_drop_message is the handler the window seam calls. A plain function (not a +// closure) so the install site reads the same on every platform that has one. +// +// It lives in this file rather than in `drop.v` because it reads an HDROP, and +// `drop.v` is platform-neutral and may not name a platform function: keeping it +// there made the entire `services` module fail to compile on Linux. `drop.v` +// carries the full note on why that split falls where it does. +// +// It consumes exactly the messages `decide_drop` says are the drop's, and it reads +// the DROPFILES handle on none other. Reading lParam as an HDROP for a message +// that is not WM_DROPFILES would hand the shell API a pointer to whatever the +// message's lParam happened to be, so `is_drop_message` is asked first and the +// question is not "was it a drop" but "whose handle is this". +// +// A failed emit fails the handler, which the host treats as consumed: a drop the +// frontend never hears about is a drop the user is still holding files for, and +// there is nothing useful to pass on to a window procedure that does not know +// what a DROPFILES handle is. +fn on_drop_message(st &DropState, e webview.HostEvent) !bool { + if decide_drop(e, 0) == .pass_on { + return false + } + // The native read releases the handle as part of reading it, on every path + // including an error - an unreleased HDROP is a shell resource leak per drop, + // and a drop is something a user can do a hundred times an hour. + paths := read_dropped_paths_native(e.lparam) or { + return error('drop: could not read the dropped paths: ' + err.msg()) + } + st.ctx.emit(event_drop_files, drop_files_data(validate_dropped_paths(paths)))! + return true +} + fn enable_drop_native(mut st &DropState) ! { require_parent(st.ctx, 'drop.enable')! if st.hook == unsafe { nil } { - // `owner` rather than `st` in the capture: V 0.5.2 types a closure - // capture of a `mut` pointer *parameter* as a pointer to the pointer and - // gcc rejects the generated assignment. A plain local captures correctly - - // the same workaround as set_tray_native, for the same reason. + // `owner`, not `st`: see webview.attach's "One caller-side rule". owner := st hook := webview.attach(st.ctx, fn [owner] (e webview.HostEvent) !bool { return on_drop_message(owner, e)! diff --git a/webview/jobs_test.v b/webview/jobs_test.v index c8fba53..6a2a014 100644 --- a/webview/jobs_test.v +++ b/webview/jobs_test.v @@ -157,9 +157,30 @@ fn test_post_to_main_refuses_a_window_with_no_wakeup() { post_to_main(c, fn [mut ran] () { ran.count++ }) or { why = err.msg() } assert ran.count == 0 assert why.contains('post_to_main') - assert why.contains('wakeup') + // The refusal NAMES the half that is missing, and which half that is differs + // by platform — so the word differs and one fixed word cannot assert both. + // + // Windows subclasses the window, and the subclass IS the wakeup, so a window + // that could not be subclassed has a queue nothing will ever drain. Linux has + // no wakeup at all: there is no half of one, because the g_idle_add seam that + // would own it is unwritten (ADR-0019), and post_to_main refuses outright + // rather than pretending to queue. + // + // Asserting 'wakeup' unconditionally is what made this file fail on Linux, and + // simply dropping the line would have been the other mistake: a check that + // cannot fail on one platform is not a weaker check, it is no check. Each + // branch below asserts its own platform's actual message, including the + // 'linux' spelling that distinguishes the deliberate branch from the generic + // "not available on this platform" fallback. + $if windows { + assert why.contains('wakeup') + } $else $if linux { + assert why.contains('linux') + assert why.contains('g_idle_add') + } // And it refused BEFORE queueing, so the queue is not holding a job that - // nothing will ever run. + // nothing will ever run. This is the platform-neutral half of the property and + // it is asserted everywhere. assert mt.queue.jobs.len == 0 mt.destroy() } diff --git a/webview/webview_linux.c.v b/webview/webview_linux.c.v index 3222215..5d7a64c 100644 --- a/webview/webview_linux.c.v +++ b/webview/webview_linux.c.v @@ -30,6 +30,15 @@ fn C.vails_message_body(result voidptr) &char fn C.vails_add_runtime(manager voidptr, js &char) fn C.g_free(mem voidptr) +// F0's last-window rule (the Linux half). Both live in webview_linux_shim.h - +// they are `static inline` there, which is why gcc cannot see them from here +// until they are declared: an `#insert`-ed header provides definitions, and V +// still needs to be told each signature it calls. Declaring the pair is what +// makes `destroy_cb` and `run_linux` compile; neither function existed in this +// list before the multi-window work, and the C half was written first. +fn C.vails_window_opened() +fn C.vails_window_closed() + fn C.gtk_init(argc &int, argv &&char) fn C.gtk_main() fn C.gtk_main_quit() @@ -68,8 +77,7 @@ fn C.gtk_widget_get_visible(widget voidptr) int // after gtk_widget_show_all. fn C.gtk_widget_get_window(widget voidptr) voidptr -// GTK_ORIENTATION_VERTICAL (1) and GDK_WINDOW_TYPE_HINT (0) as literals -// (AGENTS.md §2). gtk_window_new is called with 0, which is GTK_WINDOW_TOPLEVEL. +// GTK_ORIENTATION_VERTICAL and GTK_WINDOW_TOPLEVEL as literals (AGENTS.md §2). const gtk_orientation_vertical = 1 const gtk_window_toplevel = 0 @@ -97,11 +105,16 @@ fn js_trampoline() {} // and C never dereferences it - it only ferries the pointer back to the // callback. Heap-allocated, freed after gtk_main returns. struct DispatchCtx { - view voidptr - router &bridge.Router - label string - reg capabilities.Registry - runtime string + view voidptr + router &bridge.Router + label string + reg capabilities.Registry + // `runtime` used to be a fifth field here, carrying the injected bridge + // source per window. Nothing ever read it — `message_cb` uses `view`, + // `router`, `label` and `reg` and never the script text, because the + // script goes to WebKit as a user script at build time + // (vails_add_runtime) and is not needed again. It was dead the whole time + // it was here, and only the Linux run could have said so. } // message_cb is the single JS->V entry point on Linux. It runs on the GTK main @@ -146,9 +159,13 @@ fn message_cb(result voidptr, data voidptr) { // is one context per window, each carrying ITS OWN label, which is what makes // a command called from the settings window gated against the settings // window's capabilities (F0 makes that load-bearing). -fn build_linux_window(cfg Config, win &Window) &DispatchCtx { - // GTK_WINDOW_TOPLEVEL == 0 - window := C.gtk_window_new(0) +fn build_linux_window(cfg Config, mut win &Window) &DispatchCtx { + // The named constant, not a bare 0. This call used to pass the literal with + // `// GTK_WINDOW_TOPLEVEL == 0` written above it, which left + // `gtk_window_toplevel` declared and never referenced anywhere in the + // repository — a constant that exists to name a magic number, defeated by + // the one call site that should have used it. + window := C.gtk_window_new(gtk_window_toplevel) if window == unsafe { nil } { return unsafe { nil } } @@ -181,7 +198,10 @@ fn build_linux_window(cfg Config, win &Window) &DispatchCtx { free(ctx) return unsafe { nil } } - C.vails_add_runtime(manager, label_js(bridge.runtime_js(), cfg.label)) + // `.str` because vails_add_runtime takes a `&char`: label_js returns a + // V string, and handing a V string where a C char pointer is wanted is + // the mismatch webview_windows.c.v:348 already spells the same way. + C.vails_add_runtime(manager, label_js(bridge.runtime_js(), cfg.label).str) C.g_signal_connect_data(window, c'destroy', voidptr(destroy_cb), nil, nil, 0) } // The webview goes into a vertical box rather than straight into the @@ -265,11 +285,11 @@ fn run_linux(cfgs []Config) ! { // Build them all before the loop starts: on_ready for window 2 must not run // while window 1's loop is already spinning, and GTK wants every window // realized before the first iteration. - contexts := []&DispatchCtx{} + mut contexts := []&DispatchCtx{} for cfg in cfgs { - win := reg.find(cfg.label) + mut win := reg.find(cfg.label) C.vails_window_opened() - ctx := build_linux_window(cfg, win) + ctx := build_linux_window(cfg, mut win) if ctx == unsafe { nil } { // Roll the counter back: a run that never reaches gtk_main must // not leave the process believing a window is still open. From 8a0c4e6b1ee8b715aed25072c86122b70f1327e6 Mon Sep 17 00:00:00 2001 From: metif12 Date: Mon, 5 Oct 2026 15:53:46 +0330 Subject: [PATCH 02/29] services/menu: set_menu fails when the bar cannot be hooked, instead of swallowing it attach_bar_hook caught the webview.attach error, eprintln'd it and returned normally, so menu.set_menu resolved ok on a window whose bar was attached with nothing listening to it - a dead menu bar and no error anywhere. The comment above the eprintln even claimed the opposite ("the whole command fails: the caller learns"), so the code and its own stated contract disagreed. tray and drop propagated the identical failure from the identical call. attach_bar_hook now returns ! and the error propagates. The hook is installed BEFORE SetMenu rather than after, so there is no window in which a click can arrive for a menu the window is not yet routing, and a failure destroys the HMENU it just built instead of leaking it. Two tests, seen red by planting the eprintln back: one at the native seam (test_a_bar_that_cannot_be_hooked_fails_the_command) and one through the command (test_set_menu_refuses_a_window_it_cannot_hook). The first test is wrapped in a Windows-only compile-time branch, because attach_bar_hook lives in menu_windows.c.v. An earlier version of its comment claimed the guard was cross-platform on the grounds that webview.attach is; the test did not compile on Linux. The cross-platform half of the contract is asserted through set_menu instead, which both backends gate on the window first. --- services/menu_test.v | 67 ++++++++++++++++++++++++++++++++++++++ services/menu_windows.c.v | 68 ++++++++++++++++++++++++++++++--------- 2 files changed, 119 insertions(+), 16 deletions(-) diff --git a/services/menu_test.v b/services/menu_test.v index 9efaf9a..0bd50a3 100644 --- a/services/menu_test.v +++ b/services/menu_test.v @@ -258,6 +258,73 @@ fn cmd(wparam u64) webview.HostEvent { } } +// A bar that cannot be hooked must FAIL, not quietly do nothing. +// +// This is the regression guard for a swallowed failure. `attach_bar_hook` used to +// catch the `webview.attach` error, `eprintln` it and return normally, so +// `menu.set_menu` resolved `ok` on a window whose bar was attached and had nothing +// listening — a dead menu bar with no error anywhere, while `tray` and `drop` +// propagated the identical failure from the identical call. The comment above the +// old `eprintln` even claimed the opposite ("the whole command fails: the caller +// learns"), so the code and its own stated contract disagreed. +// +// It is testable WITHOUT a window on Windows because `webview.attach` rejects a +// parentless `Ctx` before it reaches any `$if` — the check is `ctx.has_parent()`, +// not the platform. So this needs no HWND, which is the only reason it is an +// assertion here rather than a note in the E2E README. +// +// The `$if windows` is nonetheless required, and the reason is worth stating +// because it is the more common way this guard gets lost: `webview.attach` is +// cross-platform, but `attach_bar_hook` — the function under test — is not. It +// lives in `menu_windows.c.v`, so a "both platforms" test naming it does not +// merely skip on Linux, it fails to compile. The cross-platform half of the same +// contract is asserted by `test_set_menu_refuses_a_window_it_cannot_hook` below, +// which goes through `set_menu`, and both backends gate on the window first. +// +// What this does NOT cover, stated plainly so the guard is not over-read: a +// `SetWindowSubclass` failure on a real HWND still cannot be reached from a unit +// test, so the native half of this failure mode is argued in the comment on +// `attach_bar_hook` and proven by the menu E2E run, not asserted here. +$if windows { + fn test_a_bar_that_cannot_be_hooked_fails_the_command() { + mut st := &MenuState{ + ctx: webview.Ctx{ + label: 'main' + } + } + mut why := '' + attach_bar_hook(mut st) or { why = err.msg() } + assert why.contains('menu.set_menu') + assert why.contains('hook') + // And nothing was half-installed: a nil hook is what makes the caller's + // `or` branch safe to run, because it destroys the orphan HMENU knowing no + // seam will ever read it. + assert st.bar_hook == unsafe { nil } + assert st.bar_handle == unsafe { nil } + } +} + +// The hook is installed BEFORE the bar is handed to the window, and this is the +// pure-V half of why: a `menu.set_menu` that reaches the native layer with no +// window must fail, so no HMENU is ever attached to a window whose seam is +// missing. (The ordering itself is in `set_menu_native` and needs a real HWND; +// what is checkable here is that the command refuses rather than half-succeeding.) +fn test_set_menu_refuses_a_window_it_cannot_hook() { + mut st := &MenuState{ + ctx: webview.Ctx{ + label: 'main' + } + } + mut why := '' + set_menu(mut st, [MenuItem{ + id: 'file' + label: 'File' + }]) or { why = err.msg() } + assert why != '' + assert st.bar_handle == unsafe { nil } + assert st.bar_hook == unsafe { nil } +} + fn test_bar_click_maps_a_command_id_back_to_its_item() { ids := bar_ids_fixture() // 1-based, because 0 is reserved for "no command" on Windows and for "no diff --git a/services/menu_windows.c.v b/services/menu_windows.c.v index bae939e..eb1e7ac 100644 --- a/services/menu_windows.c.v +++ b/services/menu_windows.c.v @@ -214,6 +214,28 @@ fn set_menu_native(mut st &MenuState, items []MenuItem) ! { // Set BEFORE the bar goes on the window, so a WM_COMMAND cannot arrive // before the table that decodes it exists. st.bar_ids = b.ids + // Hook BEFORE the bar, so a seam that cannot be installed leaves the window + // untouched. This is the order `drop_windows.c.v` argues for at length and + // the reverse of what was here: SetMenu used to run first and the hook + // second, so propagating the attach failure (which it now does) would have + // reported an error *and* left a visible bar that swallows every click. + // Arm-then-hook is only safe while the failure is swallowed, which is the + // bug; once the failure propagates, the seam has to come first. + // + // `or` rather than `!` so the HMENU is released on the way out: CreateMenu + // already succeeded and nothing owns this handle — it was never handed to + // SetMenu — so bailing with `!` would leak one menu per failed attach, which + // is the same class of leak drop_windows.c.v refuses for HDROP. + // + // Replacing a bar cannot fail here: the hook is already installed, so + // attach_bar_hook returns immediately and the id table above is simply + // swapped underneath it. + attach_bar_hook(mut st) or { + unsafe { + C.DestroyMenu(root) + } + return err + } previous := unsafe { C.SetMenu(st.ctx.parent, root) } if previous != unsafe { nil } { unsafe { @@ -226,42 +248,56 @@ fn set_menu_native(mut st &MenuState, items []MenuItem) ! { C.DrawMenuBar(st.ctx.parent) } st.bar_handle = root - attach_bar_hook(mut st) } // drop_bar_hook removes the seam installed for the bar. Called when the bar // goes away, because a hook with nothing to decode ids for would classify every // WM_COMMAND as "not ours" forever — harmless but no longer the reason it exists. +// +// Clear the field BEFORE detaching, which is tray's ordering and the one adopted +// here. If removal could re-enter (a message already in flight, say) it then +// finds nothing to detach a second time, which is the outcome you want; the +// reverse order leaves a window in which a second detach is reachable. +// +// The nil guard is load-bearing and cannot be moved into webview.detach: V 0.5.2 +// faults on handing a nil *variable* to a `mut &T` parameter, before the callee +// runs at all (AGENTS.md §2c). See that function's doc comment. fn drop_bar_hook(mut st &MenuState) { if st.bar_hook == unsafe { nil } { return } - webview.detach(mut st.bar_hook) + mut hook := st.bar_hook st.bar_hook = unsafe { nil } + webview.detach(mut hook) } -// attach_bar_hook installs the window seam for the bar's WM_COMMAND, unless it -// is already installed (replacing the bar's items must not stack hooks). +// attach_bar_hook installs the window seam for the bar's WM_COMMAND, unless it is +// already installed (replacing the bar's items must not stack hooks). +// +// `owner` rather than `st` in the capture: see webview.attach's "One +// caller-side rule", which is the one copy of that V 0.5.2 rule. // -// `owner` rather than `st` in the capture: V 0.5.2 types a closure capture of a -// `mut` pointer *parameter* as a pointer to the pointer and the generated C -// assignment is rejected by gcc. Same workaround as tray_backend, same reason. -fn attach_bar_hook(mut st &MenuState) { +// **It returns the failure rather than logging it**, which it used to do. The +// earlier version caught the attach error, wrote it to stderr with `eprintln` and +// returned normally — so `menu.set_menu` resolved `ok` on a window whose bar was +// attached but had nothing listening, and the user clicked a dead menu bar with +// no error anywhere. That is the opposite of what a comment three lines above it +// claimed to be preventing ("the whole command fails: the caller learns, and +// the frontend can fall back"), and it was inconsistent with `tray` and `drop`, +// which both propagate the identical failure from the identical `webview.attach` +// call. A command that cannot do its job must say so; AGENTS.md §2 puts failures +// in the return value, not on stderr. +fn attach_bar_hook(mut st &MenuState) ! { if st.bar_hook != unsafe { nil } { return } owner := st - hook := webview.attach(st.ctx, fn [owner] (e webview.HostEvent) !bool { + st.bar_hook = webview.attach(st.ctx, fn [owner] (e webview.HostEvent) !bool { return on_bar_command(owner, e)! }) or { - // A bar with no hook is a bar the user can click and nothing will - // happen, which is worse than no bar at all, so the whole command - // fails: the caller learns, and the frontend can fall back. - eprintln('menu.set_menu: could not hook the window for menu commands: ' + - err.msg()) - return + return error('menu.set_menu: could not hook the window for menu ' + + 'commands: ' + err.msg()) } - st.bar_hook = hook } // on_bar_command is the handler for the bar's seam. It consumes a WM_COMMAND From ffd2271243b5c07db454064716a5e95239d8c42c Mon Sep 17 00:00:00 2001 From: metif12 Date: Mon, 5 Oct 2026 15:56:31 +0330 Subject: [PATCH 03/29] services/dts: mark the blocking commands in the generated .d.ts Four commands open a native dialog: dialog.message, dialog.open, dialog.save and menu.popup. A call to one of them does not resolve until a human answers, which is the single most surprising thing about the API from a TypeScript editor's point of view, and the generated declaration said nothing about it. services.dts now emits a JSDoc note for those four. Three tests: one asserts the marker appears for a blocking command, one asserts it does NOT appear for a non-blocking one (so the marker cannot spread by accident), and one pins the set so a fifth blocking command shipped without a marker fails the suite. The checked-in examples/*/frontend/vails.d.ts cannot be regenerated yet - vails dts cannot read vails.json because of a V compiler bug - so those three files are one release behind. They say "do not edit" in their header, so they are left alone and the gap is recorded in CHANGELOG under "Not done". --- services/dts.v | 30 +++++++++++ services/dts_test.v | 118 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+) diff --git a/services/dts.v b/services/dts.v index 743bcd9..9bd1ecb 100644 --- a/services/dts.v +++ b/services/dts.v @@ -31,6 +31,22 @@ pub fn (s Service) specs() []generator.MethodSpec { // function per command. The names are the short ones the per-service JS // snippet installs on window.vails, so a frontend type-checks the same // shape it calls at runtime. +// +// **A blocking command carries a JSDoc marker above its declaration**, and +// that is the whole point of the `blocking` field reaching this function at +// all. ADR-0014 says the flag exists "so the constraint is visible in the +// service description, not only in prose" — and until now it was in neither: +// `dts` emitted a bare signature, so the generated `.d.ts` a frontend +// type-checks against was byte-identical whether a command froze the UI or +// not. A frontend author had to go and read ADR-0014 to learn that +// `dialog.open` blocks until the user answers, and nothing in their editor +// would have told them. +// +// A JSDoc comment rather than a change to the signature, because the flag is +// documentation and not part of the type: `dialog.open` takes the same +// arguments and returns the same `Promise` whether it blocks or not, and +// inventing a wrapper type to encode "blocks the UI" would be a lie about the +// runtime shape. pub fn dts(svcs []Service) string { mut out := '' for s in svcs { @@ -41,6 +57,9 @@ pub fn dts(svcs []Service) string { out += '\texport const service: string;\n' out += '\texport const version: string;\n' for c in s.commands { + if c.blocking { + out += '\t/** ' + blocking_note(c) + ' */\n' + } out += '\texport function ' + c.short_name() + '(params: ' + params_type(c) + '): Promise<' + c.result + '>;\n' } @@ -49,6 +68,17 @@ pub fn dts(svcs []Service) string { return out } +// blocking_note is the one-line warning a frontend author reads at the call +// site. It says what the call does and what the constraint is, because "this +// blocks" alone reads as a performance note rather than as "do not put this on +// a path that must stay responsive". +fn blocking_note(c Command) string { + return c.short_name() + ' blocks the UI until it is answered (a native ' + + 'modal). Do not call it from a loop or a startup path; it is the ' + + 'documented exception to the "handlers must be fast" threading rule ' + + '(ADR-0014).' +} + // params_type is the .d.ts parameter type of one command: `undefined` // for a no-argument command, the declared type otherwise. fn params_type(c Command) string { diff --git a/services/dts_test.v b/services/dts_test.v index eaa86d0..3e5f6b2 100644 --- a/services/dts_test.v +++ b/services/dts_test.v @@ -73,3 +73,121 @@ fn test_snippets_are_prefixed_per_service() { fn test_snippets_of_nothing_is_empty() { assert snippets([]) == '' } + +// --- Command.blocking must reach the service description (ADR-0014) --- +// +// ADR-0014 justifies the `blocking` flag with one sentence: the manifest marks +// these commands "so the constraint is visible in the service description, not +// only in prose". Before this was wired, `dts` emitted a bare signature and the +// flag was in neither — the generated `.d.ts` a frontend type-checks against was +// byte-identical whether a command froze the UI or not. +// +// These three tests are the enforcement, and they are deliberately two-sided. +// A test that only asserted "blocking commands are marked" would pass if `dts` +// marked *everything*, which is the same failure mode as a guard that cannot +// fail: it would look like coverage while checking nothing. + +fn blocking_demo() Service { + return Service{ + name: 'demo' + version: '0.1.0' + summary: 'test service' + commands: [ + Command{ + name: 'demo.slow' + params: '{ }' + result: 'string' + blocking: true + }, + Command{ name: 'demo.fast', result: 'void' }, + ] + } +} + +fn test_a_blocking_command_is_marked_in_the_generated_description() { + out := dts([blocking_demo()]) + assert out.contains('/** slow blocks the UI until it is answered') + // The marker must be the line IMMEDIATELY above the declaration it + // describes. TypeScript attaches a JSDoc comment to the declaration that + // follows it, and to the wrong one otherwise — so "somewhere earlier in the + // file" is not good enough, and a character-count heuristic is not either + // (the note is prose and its length is not the property). + lines := out.split('\n') + mut note := -1 + for i, l in lines { + if l.contains('/** slow blocks') { + note = i + } + } + assert note >= 0 + mut next := note + 1 + for next < lines.len && lines[next].trim(' \t') == '' { + next++ + } + assert lines[next].contains('export function slow(') + // And the marker names the rule, so a reader knows it is deliberate rather + // than a performance hint. + assert out.contains('ADR-0014') + assert out.contains('documented exception') +} + +fn test_a_non_blocking_command_is_not_marked() { + // The other half, and the reason this file is worth having: a generator that + // marked everything would satisfy the test above on its own. + out := dts([blocking_demo()]) + assert !out.contains('fast blocks') + assert out.contains('export function fast(params: undefined): Promise;') + // Exactly one marker, for exactly one blocking command. + assert out.split('/**').len - 1 == 1 +} + +// The flag is a POLICY boundary, so the set of commands on the wrong side of it +// is pinned rather than derived. Deriving it ("every blocking command has a +// marker") is what the two tests above do; this one catches the case they cannot: +// somebody marks a new command blocking, or unmarks an existing one, and the +// marker still matches perfectly. +// +// Four commands, and the reason each is here is not interchangeable: +// - dialog.open/save/message: ADR-0014's own exception, a native modal that +// freezes until answered. +// - menu.popup: blocks on Windows (a native TrackPopupMenu loop) but NOT on +// Linux, where the GTK menu is emitted and returns immediately. It is marked +// blocking because the flag describes the worst platform, not the current +// one — worth pinning, because unmarking it would look correct from a Linux +// machine and silently break the Windows threading contract. +fn test_the_set_of_blocking_commands_is_pinned() { + // `manifests()` rather than an enumerated list of services, so a service + // added later is covered by this assertion the moment it exists — a pinned + // list of the *other* services would have needed editing here first, which + // is the same drift this is meant to catch. + mut got := []string{} + for s in manifests() { + for c in s.commands { + if c.blocking { + got << c.name + } + } + } + got.sort() + // Four, and the reason each is here is not interchangeable: + // - dialog.open/save/message: ADR-0014's own exception, a native modal that + // freezes until the user answers. + // - menu.popup: blocks on Windows (a native TrackPopupMenu loop) but NOT on + // Linux, where the GTK menu is emitted and returns immediately. It is + // marked blocking because the flag describes the worst platform, not the + // current one — worth pinning, because unmarking it would look correct + // from a Linux machine and silently break the Windows threading + // contract that ADR-0014 records. + // + // So this assertion fails two ways on purpose: a fifth blocking command + // anywhere, and a missing one here. + assert got == ['dialog.message', 'dialog.open', 'dialog.save', 'menu.popup'] + // The flag is visible in the description for every one of them, which is the + // promise being enforced: no blocking command may reach a frontend as a bare + // signature. + out := dts(manifests()) + for c in got { + short := c.all_after('.') + assert out.contains('/** ' + short + ' blocks the UI'), c + } +} From 02f38038df4f869fbf1460f5e856816ee9d486c4 Mon Sep 17 00:00:00 2001 From: metif12 Date: Mon, 5 Oct 2026 15:56:32 +0330 Subject: [PATCH 04/29] webview, services: align the three hook teardowns, and stop detach claiming nil-safety it cannot deliver tray, menu and drop each detach a webview hook, and each had its own nil check in its own shape. Collapsing those into webview.detach looked like the obvious cleanup. It is wrong, and the suite said so immediately: tray_test.v died with an unhandled access violation. The reason is a V 0.5.2 bug, measured in a standalone file with no Vails code. Passing a nil LITERAL to a mut &T parameter is safe - the nil reaches the body and a check there fires. Passing a nil VARIABLE is a hard crash (0xC0000005), before the body runs at all. So a nil check inside detach is unreachable in the only way callers actually call it, and writing one there would read as a guarantee while being dead code. detach therefore goes back to what it was, with a doc comment that says plainly why it is not nil-safe and points at AGENTS.md section 2c, so the next person does not try this again. The three callers keep their own guards. The genuine part of the cleanup survives: the capture rule is stated once in attach's comment instead of three times, and tray and menu clear the field BEFORE detaching, so a second detach is unreachable. --- services/tray_windows.c.v | 5 +---- webview/host.v | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/services/tray_windows.c.v b/services/tray_windows.c.v index 07156d0..65d60ab 100644 --- a/services/tray_windows.c.v +++ b/services/tray_windows.c.v @@ -57,10 +57,7 @@ fn set_tray_native(mut st &TrayState, opts TrayOptions) ! { // The seam is installed here, not by webview.run: an app that never shows a // tray icon gets no subclass on its window at all (ADR-0017). if st.hook == unsafe { nil } { - // `owner` rather than `st` in the capture: V 0.5.2 types a closure - // capture of a `mut` pointer *parameter* as a pointer to the pointer, and - // the generated C assignment is rejected by gcc. A plain local captures - // correctly. Same workaround as tray_backend, same reason. + // `owner`, not `st`: see webview.attach's "One caller-side rule". owner := st hook := webview.attach(st.ctx, fn [owner] (e webview.HostEvent) !bool { return on_host_message(owner, e)! diff --git a/webview/host.v b/webview/host.v index b02412f..0629832 100644 --- a/webview/host.v +++ b/webview/host.v @@ -115,6 +115,23 @@ pub fn (h &HostCtx) has_handler() bool { // to subclass. A Linux service does not call this — it connects the signal of // the GTK object it owns — so the error below names the real reason instead of // reporting a missing dependency. +// +// ## One caller-side rule, written here once because three call sites needed it +// +// V 0.5.2 mis-types a closure capture of a `mut` **pointer parameter** as a +// pointer to the pointer, and gcc rejects the generated assignment. A plain +// **local** of the same pointer captures correctly. So a caller holding its +// state as `mut st &SomeState` must do this: +// +// ```v +// owner := st // a plain local copy of the pointer +// hook := attach(st.ctx, fn [owner] (e HostEvent) !bool { … on_msg(owner, e) … }) +// ``` +// +// and not capture `st` itself. This paragraph is the single copy on purpose: +// the rule was originally written out in full at all three call sites +// (`tray`/`menu`/`drop` on Windows), which is three comments that will drift. +// They now point here. pub fn attach(ctx Ctx, on_event HostHandler) !&HostCtx { if !ctx.has_parent() { return error('vails: attach needs the window handle (pass the Ctx from ' + @@ -137,6 +154,14 @@ pub fn attach(ctx Ctx, on_event HostHandler) !&HostCtx { // detach removes the hook and frees the context. Safe on a context that never // attached (a Linux service's hook, or a failed attach), because removal is // guarded on the handle. +// +// **It is NOT safe to call with a nil context**, and there is deliberately no +// nil check here to make it so — one was tried and removed. A nil check inside +// the body cannot help, because the crash happens before the body runs: V 0.5.2 +// faults on passing a nil *variable* to a `mut &T` parameter (measured, AGENTS.md +// §2c), and writing `if host == unsafe { nil } { return }` here would have read +// as a guarantee while being unreachable in the only way callers actually call +// it. Callers must guard, which is why `tray`/`menu`/`drop` each still do. pub fn detach(mut host &HostCtx) { $if windows { detach_native(mut host) From 64cad001a6c6f53bb3c666b625ead9691c1eda65 Mon Sep 17 00:00:00 2001 From: metif12 Date: Mon, 5 Oct 2026 15:56:32 +0330 Subject: [PATCH 05/29] services: make toast_available private, because no .c.v function has a caller outside its own file --- services/notification_windows.c.v | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/services/notification_windows.c.v b/services/notification_windows.c.v index 0f9cf63..00b6fa9 100644 --- a/services/notification_windows.c.v +++ b/services/notification_windows.c.v @@ -53,7 +53,23 @@ fn is_supported_native() bool { // frontend-facing question, and a runtime probe behind it would make a // compile-time fact impure (and cost a native call per frontend check). // `vails doctor` is where a machine-specific answer belongs. -pub fn toast_available() bool { +// +// **Private, and it used to be the only `pub fn` in any of the 24 `.c.v` +// files.** That is not a style note: a `pub` in a platform-suffixed file makes +// the `services` module's public API differ per platform, so `services.X` is a +// name that exists on Windows and not on Linux — the exact shape of the bug +// class that stopped the whole module compiling on Linux on 2026-10-05 +// (`drop.v` calling a Windows-only function from platform-neutral code). The +// repo's own rule is that platform code stays behind a neutral facade, and the +// neutral door for this question is `notification_support()`, which reaches the +// same capability through `toast_failure_reason()`. +// +// It is kept, private, rather than deleted because `support_test.v` uses it as +// the independent half of a cross-check: `notification_support().ready == +// toast_available()` asserts that the newer reason-code probe and the older +// direct bool probe still agree about this machine. That is worth having, and +// it does not require the function to be public — the test is in this module. +fn toast_available() bool { unsafe { return C.vails_toast_available() == 1 } From 2bbfa0082f02cd78798bae5ccbf605e71e7ea7b0 Mon Sep 17 00:00:00 2001 From: metif12 Date: Mon, 5 Oct 2026 15:57:16 +0330 Subject: [PATCH 06/29] buildplan: guard the shape of a json2 + net.http exposure we cannot test for With net.http linked into a binary, V master (bb0d229) returns a ZERO-valued struct and no error from json2.decode[T] when the decode is instantiated in a module other than the one importing net.http. Measured as seven separate binaries; AGENTS.md section 1b has the table. The consequence in this repository is that the vails CLI cannot read vails.json: doctor, run, build and dts all report a valid config as "name must not be empty". v test . was 44/44 green throughout, because each _test.v is its own binary and no test file links dev with config. The failing combination was never assembled. That is the gap this file closes, in the only way available: it cannot assert the bug itself (a test that reproduces it would pass only while the compiler is broken, and would go red on the fix), so it asserts the precondition instead. - net.http still has exactly one importer, and it is dev - that importer and every json2.decode instantiator stay DISJOINT, because a module that both would put the zero struct inside the decoder itself - cli is still the one module joining the two halves - and the scan really does find both halves, so it cannot pass on an empty set Seen red by planting an import net.http into config.v: three assertions failed, naming the file and line, before the plant was reverted. Also corrects the first version of the diagnosis. "net.http is the trigger" is wrong: decoding a 2-field struct with net.http works, and so does decoding a struct declared in main that is a field-for-field copy of VailsConfig. Both halves are needed, and neither is sufficient. --- buildplan/json2_import_test.v | 166 ++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 buildplan/json2_import_test.v diff --git a/buildplan/json2_import_test.v b/buildplan/json2_import_test.v new file mode 100644 index 0000000..34bfc8e --- /dev/null +++ b/buildplan/json2_import_test.v @@ -0,0 +1,166 @@ +module buildplan + +import os + +// json2_import_test.v - guards the repository against *widening* a V compiler +// bug that already cost this project one broken command, silently. +// +// ## The bug +// +// Measured 2026-10-05 on V master `bb0d229`: with `net.http` linked into a +// binary, `json2.decode[T]` returns a **zero-valued `T` and no error** if the +// decode is instantiated in a module other than the one importing `net.http`. +// +// The bisection, one cell per binary (AGENTS.md §1b has the full table): +// +// json2 alone, type in main ............................ works +// json2 + net.http, type in main ...................... works <- the trap +// json2 + net.http, type declared in main (same shape) . works <- the trap +// json2 + config, decode of config's own type ......... works +// json2 + net.http + config, same decode ............... ZERO, no error +// +// So neither half is sufficient, and the shape of the defect is entirely +// cross-module. In this repository `dev` is the only `net.http` importer and +// `cli` is the only module that links it to `config`, which is why `vails +// doctor`, `vails run`, `vails build` and `vails dts` all report a valid +// `vails.json` as "name must not be empty". +// +// ## Why `v test .` never saw it +// +// Each `_test.v` is its own binary and no test file links `dev` with `config`, +// so the failing combination is never assembled. The suite was 44/44 green +// while a shipped command was broken. This file is the guard that was missing. +// +// ## Why a textual guard +// +// A behavioural one would have to link `dev` and `config` into a test binary and +// assert a decode returns a zero struct — a test that can only pass by +// reproducing a compiler bug, and which the V fix turns red. Asserting the +// *shape* of the exposure instead is checkable, stays meaningful while the bug +// lives, and goes red on the commit that widens the exposure. +// +// repo_root is absolute (derived from @FILE) so the check does not depend on +// the runner's working directory. The same idiom as workflow_test.v. +const repo_root = os.join_path(os.dir(@FILE), '..') + +// guard_file is excluded from the scan below: this file quotes `.decode[` and +// `net.http` as string literals, so a naive scan counts itself. +const guard_file = 'json2_import_test.v' + +// skip_dirs are the directories under the repository root that hold no +// first-party V. +const skip_dirs = ['vlib', 'thirdparty', 'node_modules', 'dist', 'zz'] + +// module_paths returns every `.v` file in the repository's first-party module +// directories, as absolute paths. +fn module_paths() []string { + mut out := []string{} + mut names := os.ls(repo_root) or { return out } + for name in names { + if name.starts_with('.') || name in skip_dirs { + continue + } + dir := os.join_path(repo_root, name) + if !os.is_dir(dir) { + continue + } + mut files := os.ls(dir) or { [] } + for f in files { + if f.ends_with('.v') && f != guard_file { + out << os.join_path(dir, f) + } + } + } + return out +} + +// imports_module reports whether body has `import ` at the start of a line. +fn imports_module(body string, name string) bool { + for line in body.split_into_lines() { + t := line.trim_space() + if t == 'import ' + name || t.starts_with('import ' + name + ' ') { + return true + } + } + return false +} + +// module_of returns the module (directory) name an absolute path belongs to, +// normalising the separator first so the answer does not depend on the host. +fn module_of(path string) string { + norm := path.replace('\\', '/') + parts := norm.split('/') + return parts[parts.len - 2] +} + +// modules_importing returns the module names whose files import `name`. +fn modules_importing(name string) []string { + mut set := map[string]bool{} + for path in module_paths() { + body := os.read_file(path) or { continue } + if imports_module(body, name) { + set[module_of(path)] = true + } + } + return set.keys() +} + +// modules_decoding_json2 returns the module names that instantiate +// `json2.decode`. +fn modules_decoding_json2() []string { + mut set := map[string]bool{} + for path in module_paths() { + body := os.read_file(path) or { continue } + if imports_module(body, 'json2') && body.contains('.decode[') { + set[module_of(path)] = true + } + } + return set.keys() +} + +fn test_net_http_has_exactly_one_importer_and_it_is_dev() { + // A second `net.http` importer would widen the exposure to every binary that + // links it, so this is a decision point rather than a number to update: + // re-run the bisection in AGENTS.md §1b before changing it. + assert modules_importing('net.http') == ['dev'] +} + +// This is the invariant the bug actually lives in. The two sets must stay +// DISJOINT: a module that both imports `net.http` and instantiates +// `json2.decode` would put the zero struct inside the decoder itself, where +// cross-module reasoning does not look and a test linking only `config` would +// reproduce it. +fn test_the_net_http_importers_and_the_json2_decoders_stay_disjoint() { + net_http := modules_importing('net.http') + decoders := modules_decoding_json2() + assert net_http.len > 0 + assert decoders.len > 0 + for m in net_http { + assert m !in decoders + } + // And the decoders are real: `config` is the one that reads vails.json. + assert 'config' in decoders +} + +// `cli` is where the two halves meet, which is why shipped commands broke +// rather than a library. Asserted so that moving config reading out of `cli` — +// the eventual fix — is a deliberate, visible change. +fn test_cli_is_the_only_module_joining_the_two_halves() { + body := os.read_file(os.join_path(repo_root, 'cli', 'vails.v')) or { + panic('buildplan: cannot read cli/vails.v: ' + err.msg()) + } + assert imports_module(body, 'dev') + assert imports_module(body, 'config') +} + +// A guard nobody can run is the failure `workflow_test.v` already refuses, so +// prove the scan finds both halves rather than passing on an empty set. +fn test_the_guard_can_still_see_both_halves() { + net_http := modules_importing('net.http') + decoders := modules_decoding_json2() + assert net_http == ['dev'] + assert decoders.len >= 3 + assert 'config' in decoders + assert 'bridge' in decoders + assert 'state' in decoders +} From 100e26a2bd5b9902ac7ede4510e272c3e123be9c Mon Sep 17 00:00:00 2001 From: metif12 Date: Mon, 5 Oct 2026 15:57:55 +0330 Subject: [PATCH 07/29] docs: stop citing evidence that does not exist, and record two stale claims as history A documentation accuracy pass. No behaviour changed. Three documents cited screenshots that have never existed in this repository - git log --all returns zero commits for tests/e2e_windows/tray.png, tests/e2e_windows/menu.png and tests/e2e_linux/dialog.png - while ADR-0017 used the first two as its evidence, ADR-0027 called the third "Linux, proven end to end", and README.md called the first the tray's E2E proof. The runs are not in doubt; the citations were evidence-shaped without evidence. Dated ADRs got errata appended rather than rewritten, so the record of what was believed on the day stays intact. Two further claims were stale, both under-reporting what the project achieves: - ROADMAP said "v test webview on Windows: cannot be run, it takes the host down", measured 4x on 2026-09-30 and again on 2026-10-03. On 2026-10-05 all six files compile AND run, twice, inside a full 45/45. What changed is not known: no test needed editing and the compiler is the same. The row keeps the history and says "currently green", not "fixed" - a claim with no known cause should not be stated without its provenance. - README said the Windows test command "carries one extra flag, and it is not optional", above a code block containing no extra flag. No link flag has been needed since the move to the V master build this project requires. The reason is kept, so the flag is recognisable as version-scoped rather than mysterious. Also adds AGENTS.md section 2c: passing a nil VARIABLE to a mut &T parameter is an access violation, and a nil check in the callee cannot prevent it. Found the hard way while trying to remove three caller-side guards. --- AGENTS.md | 121 ++++++++++++++++++++++++++ CHANGELOG.md | 126 ++++++++++++++++++++++++++++ README.md | 44 ++++++---- ROADMAP.md | 92 ++++++++++++++++---- docs/ADR/0017-window-host-seam.md | 27 ++++-- docs/ADR/0027-gtk-dialog-backend.md | 10 ++- tests/e2e_linux/README.md | 21 +++-- 7 files changed, 394 insertions(+), 47 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a75bad9..20d2960 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,6 +104,97 @@ So **no released V can build this repository.** `bridge/` and `state/` import `json2`, and a released compiler fails with `builder error: cannot import module "json2" (not found)`. +#### On V master, `json2` silently decodes to a ZERO struct when `net.http` shares the binary with a cross-module type + +Measured 2026-10-05 on master `bb0d229`. **This is the most dangerous item in +this file**, because it produces *wrong data and no error*: `json2.decode[T]` +returns a **zero-valued `T`** rather than failing, so whatever validates the +result complains about a field it never received. + +**Read the trigger before you trust it — the first version of this note was +wrong, and wrong in the useful direction.** It originally said "`json2` + +`net.http` is the broken combination". That is **not** what is happening: the +import alone is innocent. The trigger needs a *third* thing. + +Here is the whole thing, as nine standalone cells with no Vails code in the +deeper ones. Every row was built and run on this machine's compiler. + +| # | binary contains | `decode` target declared in | result | +|---|---|---|---| +| A | `json2` | `main`, 2 fields | works | +| B | `json2` + `net.http` | `main`, 2 fields | works | +| I | `json2` + `os` + `net.http` | `main`, field-for-field copy of `VailsConfig` | works | +| G | `json2` + `os` + `config` | **`config`** (`config.VailsConfig`) | works | +| **H** | `json2` + `os` + **`net.http`** + `config` | **`config`** | **zero struct, NO error** | +| E | `config` (via `config.load`) | `config` | works | +| **F** | `config` + **`net.http`** (via `config.load`) | `config` | **zero struct** | + +So the trigger is the conjunction, and all three parts are load-bearing: + +1. **`net.http` is linked into the binary**, and +2. **`json2.decode` is instantiated in a module other than the one importing + `net.http`**, and +3. **the type being decoded does not matter.** `CfgLocal` in cell I has the + same shape as `VailsConfig` and works; `VailsConfig` itself fails. What + matters is *which module* it came from, not what it contains. + +Cells I and G are the pair that pins it down: each removes exactly one of the +three conditions and turns the failure into a pass. + +Minimal reproduction — two imports, one decode, no Vails code: + +```v +module main + +import json2 +import os +import net.http +import othermod // declares `pub struct Cfg` + +fn main() { + txt := os.read_file('data.json') or { panic(err.msg()) } + cfg := json2.decode[othermod.Cfg](txt) or { + eprintln(err.msg()) // never printed + return + } + println(cfg.name) // prints empty +} +``` + +Ruled out by measurement, not assumption: not the two `cli_flags` (a build with +both still fails); not module count; not struct complexity (cell I); not the +import itself (cell B); not the JSON bytes — the same file decodes correctly in +G and H; and no module imports the old `json`. + +**Consequence for this repository: the `vails` CLI cannot read `vails.json`.** +`vails doctor`, `vails run`, `vails build` and `vails dts` all report +`vails.json: name must not be empty` on a perfectly valid project. `dev/dev.v` +and `dev/serve.v` are the only `net.http` importers, and `cli` imports `dev` for +`vails run`'s dev server — that one import is the whole exposure. + +**Why `v test .` is 45/45 green and still cannot see this:** every `_test.v` file +is its own binary, and **no test file imports both `dev` and `config`** +(`dev_test.v` is `module dev` and imports only `capabilities` and `os`). The one +import set that breaks is never linked in a test. `buildplan/json2_import_test.v` +guards the *precondition* textually instead — it cannot assert the bug, because a +test that reproduces it would only pass while the compiler is broken — but no +test here can catch a regression in the decode itself. This is the §2c lesson at +suite scale: a green check that cannot fail. + +Practical rules until this is fixed or filed: + +- Do not trust `config.load` (or any `json2.decode`) in a binary that also links + `net.http`. `vails doctor` reaching `vails.json : INVALID` is this bug, not a + bad config. +- The check that matters when reading a decode result is whether the *decoding + module* also imports `net.http`. If it does not, the result is trustworthy + even when some other module in the binary does. +- Anything that must read `vails.json` outside a test belongs in a module that + does not import `dev`. +- The checked-in `examples/*/frontend/vails.d.ts` files cannot be regenerated + with `vails dts` for this reason; they were last generated before the move to + master and say so in their header ("do not edit"). + Two consequences, and the first one inverted a decision: 1. **The Windows CI job cannot be pinned to a release.** Pinning was the right @@ -319,6 +410,36 @@ found something. mode is not consistent — the same construct crashed in one program and hung in another — so a hang and a crash here are the same bug. +- **Passing a nil VARIABLE to a `mut &T` parameter is an access violation, and a + nil check in the callee cannot prevent it.** Found during the 2026-10-05 + cleanup, and it is the nastiest of this family because the guard people reach + for *compiles, reads as a guarantee, and never runs*: + + ```v + fn detach(mut host &HostCtx) { + if host == unsafe { nil } { return } // looks safe + ... + } + + mut hook := unsafe { nil } + detach(mut hook) // 0xC0000005, and the `if` above never ran + ``` + + Measured in a standalone file with no Vails code, one cell at a time: + `takes_mut_ref(mut unsafe { nil })` passing the **literal** is **safe** — the + nil reaches the body and the check fires. `mut hook := unsafe { nil }` + followed by `takes_mut_ref(mut hook)` is a **hard crash** + (`exit -1073741819`). A plain `&T` parameter takes the same nil variable + without complaint, so the `mut` is the whole difference. + + **The rule: never rely on a callee's nil check for a `mut` reference argument + — nil-check at the call site.** And do not "fix" this by adding the check to + the callee: `webview/host.v`'s `detach` carries a comment recording that a + check was added there, the suite crashed anyway, and it was removed. The three + `webview.detach` call sites in `services/` (`tray`, `menu`, `drop`) each keep + their own guard for this reason; `tray` and `menu` clear the field *before* + detaching, so a second detach is unreachable. + **Workaround — plain reference plus `unsafe` writes**, which is what `webview_windows.c.v`'s `WindowJob` does (`#[heap]`, `unsafe { j.error = … }`): diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a31ea0..0e5dd0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,54 @@ Conventions for this file: ## [Unreleased] +### Changed + +- **Documentation accuracy pass, 2026-10-05.** No behaviour changed; three + documents no longer cite screenshots that have never existed in this repository. + `git log --all` returns **zero commits** for `tests/e2e_windows/tray.png`, + `tests/e2e_windows/menu.png` and `tests/e2e_linux/dialog.png`, yet ADR-0017 + cited the first two as its evidence, ADR-0027 cited the third as "Linux, proven + end to end", and `README.md` cited the first as the tray's "E2E proof". The runs + themselves are not in doubt — the tray loop is still machine-checked by the E2E + script's `PostMessage` -> subclass -> `tray:clicked` assertion — but the + citations were evidence-shaped without evidence, which is the one failure mode + this project cannot afford in a document other people rely on. The dated ADRs + got **errata appended rather than rewritten**, so the record of what was believed + on the day stays intact; the living docs (`README.md`, `ROADMAP.md`) were + corrected directly. One broken markdown image link removed, and the Linux + `v test` status in ADR-0017 updated from "Pending" (with a named compiler + blocker) to 44/44 green. + + Two further claims were stale in the same pass, and both were wrong in the + direction of under-reporting what the project achieves: + + - **`v test webview` on Windows.** `ROADMAP.md` said it "cannot be run: it + takes the host down", measured 4× on 2026-09-30 and again on 2026-10-03. On + 2026-10-05 all six files compile **and** run, twice, inside a full + `v -cc gcc test .`. What changed is not known — no test needed editing and + the compiler is the same. The row now records the history and labels this + *currently green*, not *fixed*, because a claim with no known cause should + not be stated without its history. + - **The Windows test command "carries one extra flag, and it is not + optional"** — over a code block that contained no extra flag. No link flag + has been needed since the move to the V master build this project requires; + `README.md` now says so and keeps the reason, so the flag is recognisable as + version-scoped rather than mysterious. +- **`menu.set_menu` now fails instead of pretending it worked.** If the window's + message hook cannot be installed, `set_menu` returns that error rather than + swallowing it, and the `HMENU` it just built is destroyed rather than leaked. + The hook is now installed *before* `SetMenu`, so there is no window in which a + click can arrive for a menu the window is not yet routing. Previously a failed + hook left the handler counting clicks against a bar that would never be + drawn. Two tests pin it: one at the native seam, one at `set_menu`. +- **`vails dts` now marks the blocking commands in the generated `.d.ts`.** The + four commands that open a native dialog — `dialog.message`, `dialog.open`, + `dialog.save`, `menu.popup` — get a JSDoc note, so an editor can tell a call + that will not resolve until a human answers from one that resolves + immediately. The set is pinned by a test, so a fifth blocking command shipped + without a marker fails the suite. (The checked-in example declarations are one + release behind — see "Not done" below.) + ### Added - **`balloon` service** (ADR-0039): `balloon.show` shows a tray balloon @@ -63,6 +111,43 @@ Conventions for this file: ### Fixed +- **`v test .` on Linux is green: 44 of 44 test files, from 20 of 44 failing.** + Measured 2026-10-05 in the CI container (`Dockerfile`, V `0.5.2 e5ab344`, + WebKitGTK 2.52.6) — the first time this had ever been run on this project. + Twenty files failed for **three** root causes, none of them flaky: + - **`services` did not compile at all on Linux**, so all 13 `services` test + files failed at once. `drop.v`'s `on_drop_message` called + `read_dropped_paths_native`, which is Windows-only: a platform-neutral module + may not name a platform function, so the *whole module* failed, not one + function. `on_drop_message` moved to `drop_windows.c.v` beside its only caller + and its only platform dependency — the same arrangement + `menu_windows.c.v`'s `on_bar_command` already used. Every testable piece + (`decide_drop`, `validate_dropped_paths`, `drop_files_data`) stayed in + `drop.v` and stays covered on both platforms. + - **`webview/webview_linux.c.v` had 7 compile errors**: `vails_window_opened` + and `vails_window_closed` were never declared on the V side (they are + `static inline` in the shim, and an `#insert`-ed header supplies definitions + but not V signatures); `label_js(...)` was passed where `vails_add_runtime` + wants a `&char`; and four `mut` errors on `win`. All seven are the F0 + multi-window work that had only ever been compiled on Windows. + - **`webview/jobs_test.v` asserted a Windows-only error string.** The refusal is + real on both platforms and the load-bearing half of the property — refused + *before* queueing, so the queue is not holding a job nothing will run — is + asserted everywhere. Only the wording is platform-specific, so each platform + now asserts its own message rather than one of them passing vacuously. + - Consequence worth stating plainly: **the six `webview` test files now run on + Linux**, which is coverage Windows cannot give at all (on Windows they take + the host down — see ROADMAP). Windows is unchanged at 44/44. +- **`app_flags` is a pure function of its `target` argument again.** Its `-cc gcc` + branch was wrapped in `$if windows`, so `app_flags(.windows)` returned `[]` when + called on Linux: a Windows build plan could only be checked on a Windows + machine, which is precisely the half-checking that taking `Target` as an + argument exists to prevent. Found by the Linux run, in the test written to catch + exactly this. The `$if` was never load-bearing — the only production caller + passes the host's own target — and `cli_flags` has always added its Windows + flags without one, which is what made the outlier visible. No real build + changes; `buildplan_test.v`'s exact-equality assertion now runs and bites on + both platforms. - **`emit_to` across windows no longer crashes the process or lie about succeeding** (F0, found by running `examples/multiwindow` on 2026-10-04 — two defects that had shipped since 2026-09-30 behind a green `v vet`): @@ -506,6 +591,47 @@ Conventions for this file: ### Not done in this release +- **The `vails` CLI cannot read `vails.json`.** This is a V master bug, not a + Vails one: on `vlang/v` master, `json2.decode[T]` returns a **zero-valued + struct with no error** when the binary also links `net.http` **and the decode + is instantiated in a module other than the one importing `net.http`**. + `cli` imports `dev` (which imports `net.http`), so `vails doctor`, `vails run`, + `vails build` and `vails dts` all report `vails.json: name must not be empty` + on a project whose config is valid. + + Seven-cell bisection, each cell built and run separately; the full table is in + `AGENTS.md` §1b. **Note the middle of that table, because the obvious reading + is wrong:** adding `net.http` to a program that decodes a 2-field struct + **works**, and so does decoding a field-for-field copy of `VailsConfig` that + is declared in `main`. Only the *combination* with a cross-module decode fails. + A first pass at this concluded "`net.http` is the trigger" and wrote that down; + it was refuted by cell B. + + Two consequences worth stating plainly: + + - **`v test .` was 44/44 green and cannot catch this.** Each `_test.v` is its + own binary, and no test file imports both `dev` and `config`, so the one + import set that breaks is never linked in a test. + - **The checked-in `examples/*/frontend/vails.d.ts` files cannot be + regenerated**, so they are one release behind the generator: the + blocking-command JSDoc described under **Changed** is in `services/dts.v` + but **not yet in those three files**. They must not be hand-edited, which is + why this is listed rather than patched. + + **`buildplan/json2_import_test.v` now guards the shape of the exposure**, and + it is the guard this entry needed all along. It cannot assert the bug itself + (that would mean a test which passes only by reproducing a compiler bug, and + which the V fix turns red), so it asserts the *precondition* instead: + `net.http` still has exactly one importer, that importer and every + `json2.decode` instantiator stay **disjoint**, and `cli` is still the one place + the two meet. A second `net.http` importer, or a `net.http` import landing in a + decoding module, now goes red at review time instead of shipping a command + that reports a valid config as invalid. + + Fixing it means either an upstream V report (the right fix; `json2` was three + days old on 2026-10-03, and #28936 / #29156 are the same cross-module-symbol + family in `json2`) or keeping `net.http` out of the binary that reads config, + which means `vails run` spawning a helper process. Not done. - **`menu.set_menu` is unproven at runtime on Windows.** It compiles and links, and the pure-V classifier behind it (`bar_click`) is unit-tested on every platform, but the E2E window would not come up in the capture session, so diff --git a/README.md b/README.md index 03f1871..b8baa96 100644 --- a/README.md +++ b/README.md @@ -54,14 +54,15 @@ Current state (all verified, not promised): frontend can ask first and a documented `bundle.identifier` as its AppUserModelID; compile-verified, runtime proof pending — see `docs/ADR/0018`), **`menu`** (native popup on both platforms; the - choice arrives as an event, never as the command's result) and +choice arrives as an event, never as the command's result) and **`tray`** (Windows: a shell icon whose click reaches V through a comctl32 - subclass — `webview/host.v` — and arrives as `tray:clicked`; E2E proof in - `tests/e2e_windows/tray.png`) -- `v test .` green on **Windows** (36 test files) and on **Linux** (32 test - files as of 2026-09-28; the four new pure-V modules are OS-agnostic and - the Linux count has not been re-measured since — see - `tests/e2e_linux/README.md`) + subclass - `webview/host.v` - and arrives as `tray:clicked`; proven end to end + by the E2E script's `PostMessage` → subclass → `tray:clicked` check, which is + in `tests/e2e_windows/README.md` - no screenshot of it is committed, though an + earlier version of this line cited one) +- `v test .` green on **Windows and Linux**, **44 test files each** (measured + 2026-10-05; the Linux run was the first this project ever had, and it is what + found three real cross-platform defects - see `ROADMAP.md`) - Landed since: the window menu bar (`menu.set_menu`, ADR-0023), the tray menu (`tray.set_menu`, ADR-0026) and the GTK `dialog` (ADR-0027) - **The build track landed 2026-09-29 (ADR-0034)**: `vails build` produces a @@ -199,20 +200,29 @@ cd vails v test . # unit tests, all green, no windows opened ``` -**On Windows with gcc 16 the test command carries one extra flag, and it -is not optional:** +**On Windows with gcc the test command needs one flag, for the compiler, not for +the tests:** ```powershell $env:PATH = "C:\msys64\ucrt64\bin;" + $env:PATH -v -cc gcc test . # 33 test files (`webview` is excluded; see the ROADMAP) +v -cc gcc test . # 44 test files, `webview` included ``` -The reason is a V 0.5.2 bug rather than a Vails one: `dev/` imports -`net.http`, V's `dependency_scan_fallback` link path emits `#flag`-sourced -`-l` flags *before* most object files, and GNU `ld` only resolves an -archive against the objects that precede it — so `ws2_32` is on the link -line and cannot resolve anyway. A `#flag` in the importing module does not -help (`-ldflags` is emitted last); see ADR-0034 and `AGENTS.md` §1. +The **reason** that flag is worth knowing: `dev/` imports `net.http`, V's +`dependency_scan_fallback` link path emits `#flag`-sourced `-l` flags *before* +most object files, and GNU `ld` only resolves an archive against the objects +that precede it — so `ws2_32` is on the link line and cannot resolve anyway. A +`#flag` in the importing module does not help (`-ldflags` is emitted last); see +ADR-0034 and `AGENTS.md` §1. + +**But no link flag is needed today.** That paragraph is why the flags are +*version-scoped*, not because they are wrong: on the V master build this project +now requires (§1b of `AGENTS.md` — no released V can build it), `v -cc gcc test .` +and the CLI both link clean with no `-ldflags` and no `-cflags`, measured across +all 44 test files. If a build ever fails with `undefined reference to +__imp_connect` or `__WSAFDIsSet`, add `-ldflags "-lws2_32"` back rather than +hunting: `buildplan.cli_flags` still emits it precisely so that this stays a +version difference and not a mystery. `v test .` never opens a window. GUI checks stay manual — see `tests/e2e_windows/README.md` and `tests/e2e_linux/README.md`. @@ -439,7 +449,7 @@ v test . # must be green on Windows AND on Linux Linux (WSL Ubuntu, the `v` there is not on `PATH`): ```sh -wsl -d Ubuntu -- /root/vsrc/v test . # 29/29 +wsl -d Ubuntu -- /root/vsrc/v test . # 45/45 as of 2026-10-05 wsl -d Ubuntu -- /root/vsrc/v -gc none -o services ./examples/services ``` diff --git a/ROADMAP.md b/ROADMAP.md index d0e92ca..6c9dcd7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -11,13 +11,61 @@ an ADR, not here. | | | |---|---| -| `v test .` on Windows | **37/37 test files green**, excluding `webview` (below). No `-ldflags` needed on the current compiler — AGENTS.md §1, §1b. Re-measured 2026-10-04 across all 16 non-webview modules. | -| `v test webview` on Windows | **cannot be run**: it takes the host down. Measured 4× on 2026-09-30 and once more on 2026-10-03, one file at a time and as a directory, with **no OOM in the Windows event log**. All six `webview` test files *compile* (`v -o`, no run). | -| `v test .` on Linux | **20 of 43 test files FAIL** — measured 2026-10-05 in the CI container, the first time this has ever been run. `webview` (6 files) **compiles and runs** here, which is the coverage Windows cannot give, and it finds 7 distinct errors in `webview_linux.c.v`. `services/drop.v:257` calls `read_dropped_paths_native`, which exists only on Windows, so the module does not compile at all. `buildplan_test.v` expects `-cc gcc` in the app flags and Linux does not emit it. | +| `v test .` on Windows | **45/45 test files green, `webview` included** — measured 2026-10-05. The claim in the row below turned out to be stale. No `-ldflags` needed on the current compiler — AGENTS.md §1, §1b. | +| `v test webview` on Windows | **green as of 2026-10-05** — all six `webview` files compile *and* run, twice, inside a full `v -cc gcc test .` (45/45). This contradicts the measurement recorded here until today: **"cannot be run: it takes the host down"**, measured 4× on 2026-09-30 and once more on 2026-10-03, one file at a time and as a directory, with no OOM in the Windows event log. **What changed is not known**: the tests needed no editing to pass, and the compiler is the same 0.5.2 master as both earlier measurements. So treat this as *currently green*, not *fixed* — if it starts taking the host down again, this row is the history and the F0 work since 2026-10-03 is the first thing to suspect. | +| `v test .` on Linux | **45/45 test files green** — measured 2026-10-05 in the CI container, the first time this had ever been run. It began at **20 of 44 failing**, for three root causes: `services` did not compile at all (`drop.v` named the Windows-only `read_dropped_paths_native` from platform-neutral code), `webview_linux.c.v` had 7 compile errors from the F0 multi-window work, and `jobs_test.v` asserted a Windows-only error string. The `webview` files **run** here too — which was the point of this row while Windows could not run them, and is no longer a differentiator. | | Current phase | **Phase 5** (services) — S1 waves 1–4 and Phase 5b shipped | -| Next by the table | **CI runs now** (below). Next: the 20 Linux failures, then F1, then W1–W4 | +| Next by the table | **the Linux suite is green** (below). Next: F1, then W1–W4 | +| **Build-blocked on** | **`vails.json` cannot be loaded by the built CLI** - a V master bug, not a Vails bug. Found 2026-10-05, not yet filed upstream. See below. | | Runtime-blocked on | a display session for the Linux GUI proofs, a macOS backend (Phase 6) | +**THE CLI CANNOT READ `vails.json`, AND `v test .` CANNOT SEE IT.** Found +2026-10-05 while trying to regenerate the examples' `.d.ts` files, which had +been quietly impossible since the move to V master. Every config-consuming +command fails on a perfectly valid project: + +``` +vails doctor -> vails.json : INVALID (vails.json: name must not be empty) +``` + +`vails doctor`, `vails run`, `vails build` and `vails dts` are all +affected, so this is not one command's bug: it is the dev server's `import dev` +(which pulls in `net.http`) poisoning `json2.decode` for the whole binary. The +full bisection table and a two-import minimal reproduction are in **AGENTS.md +§1b**. + +**The trigger is narrower than "add `net.http`", and the first version of this +note was wrong about it.** `net.http` on its own is innocent: decoding a +2-field struct with `json2` + `net.http` works, and so does decoding a struct +that is a field-for-field copy of `VailsConfig`. What breaks is a decode +instantiated in a module *other than* the one importing `net.http`. Two cells +pin it down, each removing one condition and turning the failure into a pass: +the same type with `net.http` removed decodes fine, and a same-shaped type +declared in `main` decodes fine with `net.http` present. + +Three things worth remembering about it: + +- **It returns a zero-valued struct and no error.** So the complaint is about a + field that was never read ("name must not be empty"), which sends you looking + at the config file instead of at the decoder. Every config in this repo is + valid — verified by reading them, not assumed. The primitive is `json2.decode` + itself: a direct `json2.decode[config.VailsConfig]` in a binary with + `net.http` returns an empty name with no error at all, which is worse than + the CLI symptom, because nothing downstream is in a position to catch it. +- **`v test .` is 45/45 green and structurally cannot catch it**, because each + `_test.v` is its own binary and **no test file imports both `dev` and + `config`**. Same lesson as `workflow_test.v` and `bom_test.v`, one level up: + the suite is green and the property it appears to cover is exercised nowhere. +- **It is upstream.** `json2` was three days old on `vlang/v` master + (2026-10-03) and this is a cross-module codegen interaction, so the fix is a V + bug report, not a Vails patch. It joins a family the maintainers are already + working on: #28936 and #29156 are both "a same-named type in one module uses + the generated C symbol of another module's" in `json2`, and the silent-wrong- + result shape here is what that looks like when the wrong function is called. + The workaround that would unblock the CLI is to keep `net.http` out of the + binary that reads config, which means `vails run` spawning a separate helper + process — a real restructure, not done. + **CI NOW RUNS JOBS.** On 2026-10-05 this stopped being a claim. Two distinct causes had been producing the identical "0s, zero jobs" symptom, and only the second was the one the guard was written for: @@ -76,14 +124,28 @@ compiler that provably cannot build this repo, and says so in one named line instead of failing obscurely two steps later.** That is the smoke step working as designed, on a machine nobody had ever run it on. -**Which means the Linux backlog is now visible, and it is large.** 20 failing -files is not a list of flaky tests: `webview/webview_linux.c.v` has seven -distinct compile errors (two undeclared C functions, a `string`/`&char` -mismatch, four `mut` errors), `services/drop.v` references a Windows-only -function from platform-neutral code so the whole module fails, and -`buildplan_test.v` asserts a flag shape Linux does not produce. Every one of -these was shipped with the Linux side marked "stale, treat as was-green", and -stale was the correct word: nobody had run it. +**And the Linux backlog that became visible is now closed: 44 of 44 green.** It +began as 20 failing files, which is not a list of flaky tests but three distinct +compilation defects, all shipped with the Linux side marked "stale, treat as +was-green": `webview/webview_linux.c.v` had seven compile errors (two undeclared +C functions, a `string`/`&char` mismatch, four `mut` errors), `services/drop.v` +referenced a Windows-only function from platform-neutral code so the *whole* +module failed, and `buildplan_test.v` asserted a flag shape Linux does not +produce. Stale was the correct word for all three: nobody had run it. + +The fix is only interesting because of what it turned up on the way. The third one +was not a bad assertion — it was `app_flags` reading the **host** OS instead of +its `target` argument, so a Windows build plan could only ever be checked on a +Windows machine. That is the exact half-checking that taking `Target` as a +parameter exists to prevent, and the test written to catch it had been passing on +Windows the whole time, because on Windows it cannot fail. **A platform-specific +green is not a green**; it is a check that has never been exercised. The other +two are the ordinary lesson repeated: the Linux backend was never compiled +because only Windows ever compiled it. + +The lasting gain is coverage, not just colour: **the six `webview` test files run +on Linux**, which Windows cannot do at all (there they take the host down), so +`webview` now has the one platform where its tests are actually executed. **F0 is proven on Windows.** `examples/multiwindow` with `VAILS_MULTIWINDOW_PROBE=pings` brings up two windows, each showing its own label @@ -1128,8 +1190,10 @@ a small platform nicety, or a non-goal with a reason attached. - **`buildplan/dispatch_test.v` guards both bugs**, textually, because no unit test can reach C: no `webview_dispatch` call anywhere in `webview/`, and no `if (!C.webview…)` negation of a zero-is-success error code. It lives in - `buildplan` rather than `webview` because `v test webview` takes this host - down, and a guard nobody can run is the "passes because its subject is + `buildplan` rather than `webview` because it was written when + `v test webview` took this host down (see "Where we are" — that is **no + longer true as of 2026-10-05**, and moving it is now allowed but not + required), and a guard nobody can run is the "passes because its subject is missing" failure `buildplan/workflow_test.v` already refuses. Verified the only way a guard can be trusted: **red** on a reintroduced call, naming the file and line, then green. diff --git a/docs/ADR/0017-window-host-seam.md b/docs/ADR/0017-window-host-seam.md index 12c1246..f54ce76 100644 --- a/docs/ADR/0017-window-host-seam.md +++ b/docs/ADR/0017-window-host-seam.md @@ -39,12 +39,27 @@ them new for `menu`/`tray`/`webview.host`); `v -o vails ./cli` builds on both platforms and `v -gc none -o services ./examples/services` builds on Linux with all seven backends compiled in; the Windows tray click loop proven machine-checkably end to end (`PostMessage(WM_APP+1)` → subclass → V → -`ctx.emit` → the page's `tray:clicked` handler, screenshot -`tests/e2e_windows/tray.png`); a real `TrackPopupMenuEx` popup captured in -`tests/e2e_windows/menu.png`; `vails doctor` reporting 7/7 native backends on -Windows. **Pending:** the Linux `v test` run and the Linux screenshots — see -"Verification status" in `tests/e2e_linux/README.md` for the exact state and -the one compiler issue that is holding it. +`ctx.emit` → the page's `tray:clicked` handler); a real `TrackPopupMenuEx` popup +captured; `vails doctor` reporting 7/7 native backends on Windows. + +> **Erratum (2026-10-05).** This paragraph originally ended by citing two +> screenshots as its evidence — `tests/e2e_windows/tray.png` and +> `tests/e2e_windows/menu.png` — and **neither file has ever existed in this +> repository**: `git log --all` for both paths returns no commits. So the +> sentence was evidence-shaped without evidence. The tray loop is still proven by +> what the paragraph actually describes (the `PostMessage` → subclass → V → +> `ctx.emit` chain, machine-checkable, and re-run by the E2E scripts); what was +> missing was only the images, so the citation is gone rather than the claim. +> `README.md` carried the same dead `tray.png` citation and has been corrected. +> +> **Also resolved:** the trailing "**Pending:** the Linux `v test` run and the +> Linux screenshots … the one compiler issue that is holding it" is no longer +> true. Linux `v test .` runs and is **44/44 green** (measured 2026-10-05, the +> first Linux run this project ever had); the compiler issue was the whole +> `services` module failing to build because `drop.v` named a Windows-only +> function, and it is fixed. Linux screenshots other than the four committed in +> `tests/e2e_linux/` are still absent, and ADR-0027 records the same gap for the +> GTK dialog. ## Decisions diff --git a/docs/ADR/0027-gtk-dialog-backend.md b/docs/ADR/0027-gtk-dialog-backend.md index adccb41..56a8347 100644 --- a/docs/ADR/0027-gtk-dialog-backend.md +++ b/docs/ADR/0027-gtk-dialog-backend.md @@ -165,9 +165,13 @@ result shape, the ids and the parse are shared; only the widget differs. mapping to `ok`, unknown ids not guessed, only `ok`/`yes` counting as accepted, `button` always one of five names, and only `ACCEPT` meaning the chooser took files. Runs on Windows too, where there is no GTK. -- **Linux, proven end to end:** `tests/e2e_linux/dialog.png` — a real - `GtkMessageDialog` answered by a timer, reporting the button the probe - pressed. +- **Linux, proven end to end:** the probe run recorded in + `tests/e2e_linux/README.md` — a real `GtkMessageDialog` answered by a timer, + reporting the button the probe pressed. **Erratum (2026-10-05):** this bullet + cited `tests/e2e_linux/dialog.png` as its evidence, and that file has never + existed in this repository — `git log --all -- tests/e2e_linux/dialog.png` + returns no commits. The run itself is not in doubt; the *artifact* was. The + claim rests on the probe's stdout, and the linked section now says so. - **Linux, deliberately not unit-tested:** the native path, per decision 4. The test that would have done it is replaced by one that asserts the gate rejects bad input *before* the widget is built. diff --git a/tests/e2e_linux/README.md b/tests/e2e_linux/README.md index 22456ea..7ead3ea 100644 --- a/tests/e2e_linux/README.md +++ b/tests/e2e_linux/README.md @@ -455,13 +455,20 @@ cd /mnt/d/MyProjects/vails VAILS_SERVICES_PROBE=dialog sh tests/e2e_linux/run_services.sh ``` -![real GtkMessageDialog, answered by the probe, button reported](dialog.png) - -- **Fully proven, and provable without a human.** The screenshot shows a real - `GtkMessageDialog` that the probe answered from a timer, reporting - `button: ok, canceled: false`. So the whole chain is machine-checked: - `dialog.message` -> `gtk_message_dialog_new` -> `gtk_dialog_run`'s nested - main loop -> `GTK_RESPONSE_OK` -> the shared response mapping -> the page. +> **There is no committed screenshot for this run, and the image link that used +> to sit here pointed at nothing.** `tests/e2e_linux/dialog.png` has never existed +> in this repository — `git log --all -- tests/e2e_linux/dialog.png` returns no +> commits at all — yet this section and ADR-0027 both cited it as the proof. So +> the claim below rests on the probe's stdout, not on an image, and it is now +> worded as what it is. Re-capturing it is a small job on any machine with the +> GTK stack; until someone does, there is nothing in the repo to check by looking. + +- **Fully proven, and provable without a human — by the probe's report, not by a + committed screenshot.** The run reported a real `GtkMessageDialog` answered by + a timer from a `g_timeout_add`, reporting `button: ok, canceled: false`. So + the whole chain is machine-checked: `dialog.message` -> `gtk_message_dialog_new` + -> `gtk_dialog_run`'s nested main loop -> `GTK_RESPONSE_OK` -> the shared + response mapping -> the page. The "last S1 item waiting on a human answering a modal window" was not one. A `g_timeout_add` callback scheduled *before* the page's call runs inside the From 930115ca29323906b323e9fdea8a7aa31d031478 Mon Sep 17 00:00:00 2001 From: metif12 Date: Mon, 5 Oct 2026 17:14:16 +0330 Subject: [PATCH 08/29] docs: withdraw two wrong claims about the json2 decode bug, and the reproduction that did not reproduce Reviewing the upstream report before calling this done, I rebuilt its own minimal reproduction - and it printed the correct value. The bug was real; the report's reproduction was not, and neither was the trigger it stated. Two claims are withdrawn, and both were generalizations from a cell I had built but never varied. Wrong #1: "json2 + net.http is the broken combination". Refuted: decoding a 2-field struct with net.http linked works. Wrong #2: "the trigger is a cross-module decode". Refuted: the same 2-field struct in a module named `other` decodes fine with net.http linked. The trigger is two conditions together: the module declaring the decoded type is named `config`, AND net.http is linked into the binary. The module-name sweep is what pins it - `conf`, `configx`, `xconfig`, `other` and `mymod` all work, so it is the exact identifier rather than a prefix rule - and `time` and `sync` do not substitute for net.http. Struct shape is irrelevant in both directions: 2 fields fail exactly like a field-for-field copy of VailsConfig. Verified 6/6 on the failing program, deterministic, no error and exit 0. Also fixed in the upstream report: the reproduction used `other.v` as a sibling of `main.v`, which does not resolve - a module is a subdirectory when a v.mod is present, which was the second thing the first attempt got wrong. And the report now says master has moved past the compiler this was measured on (bb0d229 -> 3c5f448), with none of the five intervening commits touching vlib/json2 but d59952b changing driver/markused/ssa, so it asks for re-confirmation instead of claiming current-master breakage. The symptom in this repository was never in doubt: vails doctor reporting a valid config as invalid is exactly this bug, and the guard in buildplan is unchanged - it asserts net.http keeps one importer, that importer and the json2 decoders stay disjoint, and cli is where the two meet. All of which this repository satisfies by construction. Suite 45/45 on Windows and in the Linux container; fmt clean; encoding clean. --- AGENTS.md | 167 +++++++++++++++++----------------- CHANGELOG.md | 62 ++++++------- ROADMAP.md | 34 +++---- buildplan/json2_import_test.v | 32 ++++--- 4 files changed, 151 insertions(+), 144 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 20d2960..1e46bd1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,110 +104,115 @@ So **no released V can build this repository.** `bridge/` and `state/` import `json2`, and a released compiler fails with `builder error: cannot import module "json2" (not found)`. -#### On V master, `json2` silently decodes to a ZERO struct when `net.http` shares the binary with a cross-module type +#### On V master, `json2.decode` silently returns a ZERO struct when a module named `config` shares the binary with `net.http` Measured 2026-10-05 on master `bb0d229`. **This is the most dangerous item in this file**, because it produces *wrong data and no error*: `json2.decode[T]` returns a **zero-valued `T`** rather than failing, so whatever validates the result complains about a field it never received. -**Read the trigger before you trust it — the first version of this note was -wrong, and wrong in the useful direction.** It originally said "`json2` + -`net.http` is the broken combination". That is **not** what is happening: the -import alone is innocent. The trigger needs a *third* thing. - -Here is the whole thing, as nine standalone cells with no Vails code in the -deeper ones. Every row was built and run on this machine's compiler. - -| # | binary contains | `decode` target declared in | result | -|---|---|---|---| -| A | `json2` | `main`, 2 fields | works | -| B | `json2` + `net.http` | `main`, 2 fields | works | -| I | `json2` + `os` + `net.http` | `main`, field-for-field copy of `VailsConfig` | works | -| G | `json2` + `os` + `config` | **`config`** (`config.VailsConfig`) | works | -| **H** | `json2` + `os` + **`net.http`** + `config` | **`config`** | **zero struct, NO error** | -| E | `config` (via `config.load`) | `config` | works | -| **F** | `config` + **`net.http`** (via `config.load`) | `config` | **zero struct** | - -So the trigger is the conjunction, and all three parts are load-bearing: - -1. **`net.http` is linked into the binary**, and -2. **`json2.decode` is instantiated in a module other than the one importing - `net.http`**, and -3. **the type being decoded does not matter.** `CfgLocal` in cell I has the - same shape as `VailsConfig` and works; `VailsConfig` itself fails. What - matters is *which module* it came from, not what it contains. - -Cells I and G are the pair that pins it down: each removes exactly one of the -three conditions and turns the failure into a pass. - -Minimal reproduction — two imports, one decode, no Vails code: - -```v -module main - -import json2 -import os -import net.http -import othermod // declares `pub struct Cfg` - -fn main() { - txt := os.read_file('data.json') or { panic(err.msg()) } - cfg := json2.decode[othermod.Cfg](txt) or { - eprintln(err.msg()) // never printed - return - } - println(cfg.name) // prints empty -} +**Two earlier versions of this note were wrong, and both corrections matter more +than the claim.** The first said "`json2` + `net.http` is the broken +combination"; the second said "the trigger is a cross-module decode". Both were +generalizations from cells I had not isolated, and both were refuted by cells I +had built but not varied. The version below is the one that survives its own +controls. + +**The trigger is two conditions together, and both are load-bearing:** + +1. the module declaring the decoded type is named **`config`**, and +2. **`net.http`** is linked into the same binary. + +Verified deterministic: 6 builds of the failing program printed an empty name +every time, with no error and exit 0. + +What is *not* the trigger, each row a separate binary with the same two-field +struct and the same JSON bytes: + +| variable varied | values | result | +|---|---|---| +| module name (with `net.http`) | **`config`** | **ZERO, no error** | +| | `other`, `conf`, `configx`, `xconfig`, `mymod` | works | +| | (`cfg`) | fails to *build* — unchased, see note below | +| `net.http` (module `config`) | absent | works | +| | `time`, `sync` instead | works | +| | **`net.http`** | **ZERO, no error** | +| struct shape (module `config`) | 2 fields | **ZERO** | +| | a field-for-field copy of `VailsConfig` | **ZERO** | +| struct shape (module `other`) | 2 fields, or the same full copy | works | + +Two consequences worth internalising: + +- **The struct is irrelevant, and the module name is everything.** A copy of the + real 6-field `VailsConfig` declared in a module named `other` decodes fine; a + 2-field struct in a module named `config` does not. So "cross-module" and + "struct complexity" were both the wrong axis — the first version of this note + was confident about the second one, having never built a minimal struct in a + minimal module. +- **It is `net.http` specifically, not "a second module".** `time` and `sync` in + the same binary change nothing. And *linking* is what matters, not *use*: the + `net.http` import in the reproduction is unused, V warns about it, and the + decode is still wrong. + +Minimal reproduction, verified 6/6 — note that a module is a **subdirectory** +when a `v.mod` is present, which is the second thing my first attempt got wrong: + +``` +v.mod -> Module { name: 'repro' dependencies: [] } +config/config.v -> module config ; pub struct Cfg { pub mut: name string n int } +main.v -> import json2 / import os / import net.http / import config + json2.decode[config.Cfg](os.read_file('data.json')!) +data.json -> {"name": "vails", "n": 3} +``` + +A lead on the cause, recorded because it is cheap and offered as a **hypothesis, +not a diagnosis**: the failing and passing builds both emit + +```c +config__Cfg result = (config__Cfg){.name = _str_36}; ``` -Ruled out by measurement, not assumption: not the two `cli_flags` (a build with -both still fails); not module count; not struct complexity (cell I); not the -import itself (cell B); not the JSON bytes — the same file decodes correctly in -G and H; and no module imports the old `json`. +but define `_str_36` differently — `{"", 0, 1}` in the failing build, a long +unrelated `array.ensure_noscan` message in the passing one. So the same +`_str_N` index names different literals in the two programs, which is consistent +with a collision or a numbering computed over a differing module set. Nobody has +diffed the symbol tables yet. + +Also unchased, and deliberately not claimed: a module named **`cfg`** failed to +build three times in a row in the same harness where every other name built. **Consequence for this repository: the `vails` CLI cannot read `vails.json`.** `vails doctor`, `vails run`, `vails build` and `vails dts` all report `vails.json: name must not be empty` on a perfectly valid project. `dev/dev.v` -and `dev/serve.v` are the only `net.http` importers, and `cli` imports `dev` for -`vails run`'s dev server — that one import is the whole exposure. +and `dev/serve.v` are the only `net.http` importers, `cli` imports `dev` for +`vails run`'s dev server, and this repository's config module is named `config` +— so all three conditions are met by construction, and that one import is the +whole exposure. **Why `v test .` is 45/45 green and still cannot see this:** every `_test.v` file -is its own binary, and **no test file imports both `dev` and `config`** -(`dev_test.v` is `module dev` and imports only `capabilities` and `os`). The one -import set that breaks is never linked in a test. `buildplan/json2_import_test.v` -guards the *precondition* textually instead — it cannot assert the bug, because a -test that reproduces it would only pass while the compiler is broken — but no -test here can catch a regression in the decode itself. This is the §2c lesson at -suite scale: a green check that cannot fail. +is its own binary, and **no test file links `dev` with `config`** +(`dev_test.v` is `module dev` and imports only `capabilities` and `os`). +`buildplan/json2_import_test.v` guards the *precondition* textually instead — it +cannot assert the bug, because a test that reproduces it would only pass while +the compiler is broken — but no test here can catch a regression in the decode +itself. This is the §2c lesson at suite scale: a green check that cannot fail. Practical rules until this is fixed or filed: -- Do not trust `config.load` (or any `json2.decode`) in a binary that also links - `net.http`. `vails doctor` reaching `vails.json : INVALID` is this bug, not a - bad config. -- The check that matters when reading a decode result is whether the *decoding - module* also imports `net.http`. If it does not, the result is trustworthy - even when some other module in the binary does. +- Do not trust `config.load` (or any `json2.decode` in a module named `config`) + in a binary that also links `net.http`. `vails doctor` reaching + `vails.json : INVALID` is this bug, not a bad config. +- The check that matters is whether **the decoding module is named `config`** + and **its binary links `net.http`**. Neither condition alone does anything. - Anything that must read `vails.json` outside a test belongs in a module that does not import `dev`. - The checked-in `examples/*/frontend/vails.d.ts` files cannot be regenerated with `vails dts` for this reason; they were last generated before the move to master and say so in their header ("do not edit"). -Two consequences, and the first one inverted a decision: - -1. **The Windows CI job cannot be pinned to a release.** Pinning was the right - instinct — every other flag there is justified against a specific V — but the - only pin that works is a `vlang/v` *commit*, which means building V from source - on the runner. MSYS2 then has to be installed **before** V, because V's own - Windows build needs a C compiler. Not done. -2. **"Install a newer V" is not a complete instruction.** Newer *released* V does - not help. What helps is a V built from master. - -The trap this sits in: a machine with a master checkout builds fine, so the -dependency looks satisfied locally, and the failure only appears on a fresh -machine — which is what CI is for. +Upstream: [vlang/v#29508](https://github.com/vlang/v/issues/29508). Note that +master has moved past the compiler this was measured on (`bb0d229` → `3c5f448`) +and the fix is not ours to make. #### Two history worth keeping, because both cost an afternoon diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e5dd0d..fc7d49b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -593,45 +593,43 @@ Conventions for this file: - **The `vails` CLI cannot read `vails.json`.** This is a V master bug, not a Vails one: on `vlang/v` master, `json2.decode[T]` returns a **zero-valued - struct with no error** when the binary also links `net.http` **and the decode - is instantiated in a module other than the one importing `net.http`**. - `cli` imports `dev` (which imports `net.http`), so `vails doctor`, `vails run`, - `vails build` and `vails dts` all report `vails.json: name must not be empty` - on a project whose config is valid. - - Seven-cell bisection, each cell built and run separately; the full table is in - `AGENTS.md` §1b. **Note the middle of that table, because the obvious reading - is wrong:** adding `net.http` to a program that decodes a 2-field struct - **works**, and so does decoding a field-for-field copy of `VailsConfig` that - is declared in `main`. Only the *combination* with a cross-module decode fails. - A first pass at this concluded "`net.http` is the trigger" and wrote that down; - it was refuted by cell B. - - Two consequences worth stating plainly: - - - **`v test .` was 44/44 green and cannot catch this.** Each `_test.v` is its + struct with no error** when the module declaring `T` is named `config` **and** + `net.http` is linked into the same binary. `cli` imports `dev` (which imports + `net.http`), and this repository's config module is named `config`, so + `vails doctor`, `vails run`, `vails build` and `vails dts` all report + `vails.json: name must not be empty` on a project whose config is valid. + + Bisected one variable at a time; the full table is in `AGENTS.md` §1b, and the + upstream report is [vlang/v#29508](https://github.com/vlang/v/issues/29508). + **Two claims had to be withdrawn along the way, and both mattered:** + + - *"the trigger is a cross-module decode"* — refuted by a 2-field struct in a + module named `other`, which decodes fine with `net.http` linked. + - *"struct complexity is irrelevant"* — refuted in the other direction: the + module name is the axis. `conf`, `configx` and `xconfig` all work; `config` + does not. So it is the exact identifier, not a prefix rule. + + Two further consequences worth stating plainly: + + - **`v test .` is 45/45 green and cannot catch this.** Each `_test.v` is its own binary, and no test file imports both `dev` and `config`, so the one - import set that breaks is never linked in a test. + combination that breaks is never linked in a test. - **The checked-in `examples/*/frontend/vails.d.ts` files cannot be regenerated**, so they are one release behind the generator: the blocking-command JSDoc described under **Changed** is in `services/dts.v` but **not yet in those three files**. They must not be hand-edited, which is why this is listed rather than patched. - **`buildplan/json2_import_test.v` now guards the shape of the exposure**, and - it is the guard this entry needed all along. It cannot assert the bug itself - (that would mean a test which passes only by reproducing a compiler bug, and - which the V fix turns red), so it asserts the *precondition* instead: - `net.http` still has exactly one importer, that importer and every - `json2.decode` instantiator stay **disjoint**, and `cli` is still the one place - the two meet. A second `net.http` importer, or a `net.http` import landing in a - decoding module, now goes red at review time instead of shipping a command - that reports a valid config as invalid. - - Fixing it means either an upstream V report (the right fix; `json2` was three - days old on 2026-10-03, and #28936 / #29156 are the same cross-module-symbol - family in `json2`) or keeping `net.http` out of the binary that reads config, - which means `vails run` spawning a helper process. Not done. + `buildplan/json2_import_test.v` guards the shape of the exposure — `net.http` + keeps exactly one importer, that importer and every `json2.decode` + instantiator stay **disjoint**, and `cli` is still where the two meet — so the + combination cannot be widened without a red test. It cannot assert the bug + itself: a test that reproduces it would pass only while the compiler is broken + and would go red on the fix. + + Fixing it is upstream's. Locally the only way to unblock the CLI is to keep + `net.http` out of the binary that reads config, which means `vails run` + spawning a helper process. Not done. - **`menu.set_menu` is unproven at runtime on Windows.** It compiles and links, and the pure-V classifier behind it (`bar_click`) is unit-tested on every platform, but the E2E window would not come up in the capture session, so diff --git a/ROADMAP.md b/ROADMAP.md index 6c9dcd7..be1e50d 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -34,14 +34,15 @@ affected, so this is not one command's bug: it is the dev server's `import dev` full bisection table and a two-import minimal reproduction are in **AGENTS.md §1b**. -**The trigger is narrower than "add `net.http`", and the first version of this -note was wrong about it.** `net.http` on its own is innocent: decoding a -2-field struct with `json2` + `net.http` works, and so does decoding a struct -that is a field-for-field copy of `VailsConfig`. What breaks is a decode -instantiated in a module *other than* the one importing `net.http`. Two cells -pin it down, each removing one condition and turning the failure into a pass: -the same type with `net.http` removed decodes fine, and a same-shaped type -declared in `main` decodes fine with `net.http` present. +**The trigger is two specific conditions, and two earlier versions of this note +were wrong about it.** "`json2` + `net.http`" is not enough — decoding a 2-field +struct with `net.http` works, and so does decoding a struct that is a +field-for-field copy of `VailsConfig`. What breaks is a decode of a type declared +in a module named **`config`**, in a binary that links `net.http`. Two controls +pin it: removing `net.http` makes it pass, and renaming the module to `other` +makes it pass. `conf`, `configx` and `xconfig` all work, so it is the exact +identifier rather than a prefix rule. `time` and `sync` do not trigger it; +`net.http` does, and merely being *linked* is enough even unused. Three things worth remembering about it: @@ -57,14 +58,15 @@ Three things worth remembering about it: `config`**. Same lesson as `workflow_test.v` and `bom_test.v`, one level up: the suite is green and the property it appears to cover is exercised nowhere. - **It is upstream.** `json2` was three days old on `vlang/v` master - (2026-10-03) and this is a cross-module codegen interaction, so the fix is a V - bug report, not a Vails patch. It joins a family the maintainers are already - working on: #28936 and #29156 are both "a same-named type in one module uses - the generated C symbol of another module's" in `json2`, and the silent-wrong- - result shape here is what that looks like when the wrong function is called. - The workaround that would unblock the CLI is to keep `net.http` out of the - binary that reads config, which means `vails run` spawning a separate helper - process — a real restructure, not done. + (2026-10-03) and this needs an unusual combination to bite, so the fix is a V + bug report, not a Vails patch. Filed as [vlang/v#29508](https://github.com/vlang/v/issues/29508), + with the module-name sweep as the evidence. Note that master has already moved + past the compiler this was measured on (`bb0d229` → `3c5f448`) and none of the + five intervening commits touch `vlib/json2`, so the report asks for + re-confirmation rather than claiming current-master breakage. The workaround + that would unblock the CLI is to keep `net.http` out of the binary that reads + config, which means `vails run` spawning a separate helper process — a real + restructure, not done. **CI NOW RUNS JOBS.** On 2026-10-05 this stopped being a claim. Two distinct causes had been producing the identical "0s, zero jobs" symptom, and only the diff --git a/buildplan/json2_import_test.v b/buildplan/json2_import_test.v index 34bfc8e..8fbf01c 100644 --- a/buildplan/json2_import_test.v +++ b/buildplan/json2_import_test.v @@ -7,23 +7,25 @@ import os // // ## The bug // -// Measured 2026-10-05 on V master `bb0d229`: with `net.http` linked into a -// binary, `json2.decode[T]` returns a **zero-valued `T` and no error** if the -// decode is instantiated in a module other than the one importing `net.http`. +// Measured 2026-10-05 on V master `bb0d229`: `json2.decode[T]` returns a +// **zero-valued `T` and no error** when the module declaring `T` is named +// `config` AND `net.http` is linked into the same binary. Neither condition +// alone does it, and the controls are in AGENTS.md section 1b: removing +// `net.http` makes it pass; renaming the module to `other`, `conf`, `configx` or +// `xconfig` makes it pass; `time` and `sync` in place of `net.http` make it +// pass; and the struct's shape is irrelevant (2 fields fail exactly like a copy +// of VailsConfig). // -// The bisection, one cell per binary (AGENTS.md §1b has the full table): +// An earlier version of this comment claimed the trigger was "a cross-module +// decode". It is not - a 2-field struct in a module named `other` decodes fine +// with net.http linked. And an even earlier claim, "net.http is the trigger", was +// refuted the same way. Both were generalisations from a cell I had not isolated. // -// json2 alone, type in main ............................ works -// json2 + net.http, type in main ...................... works <- the trap -// json2 + net.http, type declared in main (same shape) . works <- the trap -// json2 + config, decode of config's own type ......... works -// json2 + net.http + config, same decode ............... ZERO, no error -// -// So neither half is sufficient, and the shape of the defect is entirely -// cross-module. In this repository `dev` is the only `net.http` importer and -// `cli` is the only module that links it to `config`, which is why `vails -// doctor`, `vails run`, `vails build` and `vails dts` all report a valid -// `vails.json` as "name must not be empty". +// In this repository `dev` is the only `net.http` importer, `cli` is the only +// module that links it to `config`, and the config module is named `config` - +// so the shipped CLI satisfies all three conditions by construction, which is +// why `vails doctor`, `run`, `build` and `dts` report a valid `vails.json` as +// "name must not be empty". // // ## Why `v test .` never saw it // From 613e7c1e75ba2d0bb99c74c8875bf8277fe8a612 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sat, 10 Oct 2026 15:51:14 +0330 Subject: [PATCH 09/29] cli, buildplan: doctor resolves the Windows toolchain through the tested helper (ADR-0038) The last of the audit items, and the only one that had been waiting on the json2 bug: `vails doctor` checked the literal path C:/msys64/ucrt64/include/webview/webview.h, so a relocated or scoped toolchain was reported against the one root that cannot be the answer. It now goes through buildplan.resolve_toolchain(), which was written and tested for this and had no production caller. A new `toolchain` line names the resolved root and where it came from - the pair that answers "why did it pick that" without opening the source, and exactly what ADR-0038 and summary()'s own doc comment say doctor should print. Every pre-existing line is unchanged in text and order. The default root IS C:/msys64/ucrt64, so an unset VAILS_TOOLCHAIN prints the identical header path; a set one follows, and whatever is missing - webview.h, libwebview.dll.a, the bin directory holding the five side-by-side DLLs - is listed once here rather than surfacing as a header error three minutes into a build. The side-by-side line deliberately still uses buildplan.ucrt64_bin, whose comment records that it matches the webview backend's own #flag -I/-L: following VAILS_TOOLCHAIN there would stage DLLs from one toolchain next to a binary built against another. Also fixes the CHANGELOG entry for the json2 bug, below, which said the CLI could not read vails.json. It can again. 45/45 on Windows and in the Linux container; fmt clean. --- CHANGELOG.md | 61 ++++++++++++++++++++++++++++--------------- README.md | 13 +++++---- buildplan/toolchain.v | 9 ++++--- cli/vails.v | 20 +++++++++++++- 4 files changed, 72 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fc7d49b..834a2f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -99,6 +99,18 @@ Conventions for this file: ### Changed +- **`vails doctor` resolves the Windows toolchain instead of asserting one + machine's path** (ADR-0038). The `webview` line checked + `C:/msys64/ucrt64/include/webview/webview.h` literally, so a relocated or + scoped toolchain was reported against the one root that cannot be the answer. + It now goes through `buildplan.resolve_toolchain()` — already the tested owner + of that decision, previously with no production caller — and a new + `toolchain` line names the resolved root and where it came from. An unset + `VAILS_TOOLCHAIN` prints the same header path as before, because the default + *is* that root; a set one follows, and any missing piece (`webview.h`, + `libwebview.dll.a`, the `bin` directory holding the five side-by-side DLLs) is + listed once, here, instead of surfacing as a header error three minutes into a + build. - **`vails doctor` now names the cause of an unavailable toast** (ADR-0039). It previously reported `REGDB_E_CLASSNOTREG`, whose two causes - a wrong AppUserModelID and a Windows with no WinRT class store - need opposite @@ -591,13 +603,16 @@ Conventions for this file: ### Not done in this release -- **The `vails` CLI cannot read `vails.json`.** This is a V master bug, not a - Vails one: on `vlang/v` master, `json2.decode[T]` returns a **zero-valued - struct with no error** when the module declaring `T` is named `config` **and** - `net.http` is linked into the same binary. `cli` imports `dev` (which imports - `net.http`), and this repository's config module is named `config`, so - `vails doctor`, `vails run`, `vails build` and `vails dts` all report - `vails.json: name must not be empty` on a project whose config is valid. +- **The `vails` CLI cannot read `vails.json`.** *(Fixed in the compiler, on + 2026-10-10 — see the end of this entry. Kept under "Not done" because the + property of this repository it exposed is still true, and the guard that + records it is unchanged.)* This was a V master bug, not a Vails one: on + `vlang/v` master, `json2.decode[T]` returns a **zero-valued struct with no + error** when the module declaring `T` is named `config` **and** `net.http` is + linked into the same binary. `cli` imports `dev` (which imports `net.http`), + and this repository's config module is named `config`, so `vails doctor`, + `vails run`, `vails build` and `vails dts` all reported + `vails.json: name must not be empty` on a project whose config was valid. Bisected one variable at a time; the full table is in `AGENTS.md` §1b, and the upstream report is [vlang/v#29508](https://github.com/vlang/v/issues/29508). @@ -609,27 +624,31 @@ Conventions for this file: module name is the axis. `conf`, `configx` and `xconfig` all work; `config` does not. So it is the exact identifier, not a prefix rule. - Two further consequences worth stating plainly: + Two consequences worth stating plainly: - - **`v test .` is 45/45 green and cannot catch this.** Each `_test.v` is its - own binary, and no test file imports both `dev` and `config`, so the one - combination that breaks is never linked in a test. - - **The checked-in `examples/*/frontend/vails.d.ts` files cannot be - regenerated**, so they are one release behind the generator: the - blocking-command JSDoc described under **Changed** is in `services/dts.v` - but **not yet in those three files**. They must not be hand-edited, which is - why this is listed rather than patched. + - **`v test .` was 45/45 green and could not catch this.** Each `_test.v` is + its own binary, and no test file imports both `dev` and `config`, so the + one combination that breaks was never linked in a test. That is a property + of this repository's test layout and it is still true. + - **The checked-in `examples/*/frontend/vails.d.ts` files were one release + behind the generator**, carrying the blocking-command JSDoc from + `services/dts.v` but not in the files themselves. They must not be + hand-edited, so the gap was listed rather than patched. `buildplan/json2_import_test.v` guards the shape of the exposure — `net.http` keeps exactly one importer, that importer and every `json2.decode` instantiator stay **disjoint**, and `cli` is still where the two meet — so the combination cannot be widened without a red test. It cannot assert the bug itself: a test that reproduces it would pass only while the compiler is broken - and would go red on the fix. - - Fixing it is upstream's. Locally the only way to unblock the CLI is to keep - `net.http` out of the binary that reads config, which means `vails run` - spawning a helper process. Not done. + and would go red on the fix. **It is unchanged by the fix**, because it is + about this repository, not about V. + + **Status: gone.** Re-measured 2026-10-10 on V master `ef2ec06` — the same + program across three fresh project roots decodes correctly, `vails doctor` + reports `vails.json : ok`, and all three example declarations were + regenerated with their blocking-command JSDoc. Nine `json2` commits landed + between the two builds and **which one fixed it is not bisected**, so it is + not attributed here. - **`menu.set_menu` is unproven at runtime on Windows.** It compiles and links, and the pure-V classifier behind it (`bar_click`) is unit-tested on every platform, but the E2E window would not come up in the capture session, so diff --git a/README.md b/README.md index b8baa96..32f93b1 100644 --- a/README.md +++ b/README.md @@ -165,9 +165,11 @@ webview packages inside the ucrt64 shell: pacman -S mingw-w64-ucrt-x86_64-webview mingw-w64-ucrt-x86_64-webview2-loader ``` -`vails doctor` looks for the header at -`C:/msys64/ucrt64/include/webview/webview.h` — if it reports MISSING, the -`pacman` step above is what fixes it. +`vails doctor` looks for the header under the *resolved* toolchain root, whose +default is `C:/msys64/ucrt64` (so it looks at +`C:/msys64/ucrt64/include/webview/webview.h`). Set `VAILS_TOOLCHAIN` to move it — +the `toolchain` line reports the root and where it came from. If the header is +MISSING, the `pacman` step above is what fixes it. Runtime DLLs are **not** linked statically. After every Windows build, copy these next to the `.exe` (all from `C:\msys64\ucrt64\bin`): @@ -263,8 +265,9 @@ v -o vails ./cli # v version : check with `v version` (need 0.5.x) # os : windows | linux | ... # on Linux : webkit2gtk version or MISSING + apt hint -# on Windows: gcc version + webview.h found/MISSING + pacman hint, -# and how many of the 5 side-by-side DLLs are present +# on Windows: the resolved toolchain root (VAILS_TOOLCHAIN, default +# C:/msys64/ucrt64) + gcc version + webview.h found/MISSING + +# pacman hint, and how many of the 5 side-by-side DLLs are present # vails.json: ok | INVALID + reason | not found (optional here) # services : which services the capabilities grant (T5) # backends : which services have a NATIVE backend on this machine, and diff --git a/buildplan/toolchain.v b/buildplan/toolchain.v index 3afeec2..499ea60 100644 --- a/buildplan/toolchain.v +++ b/buildplan/toolchain.v @@ -2,10 +2,11 @@ // // ## What this module is for // -// Four places used to name `C:/msys64/ucrt64` in code: the webview backend's -// `#flag` lines, `buildplan.ucrt64_bin`, `vails doctor`, and CI. A toolchain -// that is only reachable by editing four files is a toolchain nobody can move, so -// this resolves it once, from one knob, and every caller asks here. +// Three places still name `C:/msys64/ucrt64` in code: the webview backend's +// `#flag` lines, `buildplan.ucrt64_bin`, and CI. `vails doctor` was the fourth, +// and a toolchain that is only reachable by editing the files that happen to +// name it is a toolchain nobody can move, so this resolves it once, from one +// knob, and every caller asks here. // // ## What it deliberately does NOT do // diff --git a/cli/vails.v b/cli/vails.v index 1e41873..a6da670 100644 --- a/cli/vails.v +++ b/cli/vails.v @@ -562,18 +562,36 @@ fn doctor(args []string) { println(' appindicator: MISSING (sudo apt install libayatana-appindicator3-dev - the tray service needs it)') } } $else $if windows { + // The toolchain root comes first, because the two lines below it + // are about that root and a root the user did not expect is the + // whole mismatch ADR-0038 is about. `summary` names the root and + // where it came from, which is the pair that answers "why did it + // pick that" without opening this file. + tc := buildplan.resolve_toolchain() + println(' toolchain : ' + tc.summary()) gcc := os.execute('gcc --version') if gcc.exit_code == 0 { println(' gcc : ' + gcc.output.split_into_lines()[0]) } else { println(' gcc : MISSING (install MSYS2 ucrt64 toolchain + put C:\\msys64\\ucrt64\\bin on PATH)') } - header := 'C:/msys64/ucrt64/include/webview/webview.h' + // The header is looked up through the resolver rather than against + // a literal — a machine with a relocated or scoped toolchain used to + // be told about the one root that cannot be the answer (ADR-0038). + // The default is unchanged, so an unset VAILS_TOOLCHAIN prints the + // same path it printed before. + header := tc.include + '/webview/webview.h' if os.exists(header) { println(' webview : header found (' + header + ')') } else { println(' webview : MISSING (pacman -S mingw-w64-ucrt-x86_64-webview mingw-w64-ucrt-x86_64-webview2-loader)') } + // Everything else the resolver could not find, all at once rather + // than one failed build at a time. A whole toolchain prints nothing + // here, which is why this loop is not on the happy path. + for problem in tc.problems { + println(' ! ' + problem) + } // The five DLLs a built app cannot start without. Reported as a // count of what is actually present, because `vails build` copies // them and a build that silently could not is the failure this From 95f0879ade09ca1515b6aff0a38051f30ffb02bb Mon Sep 17 00:00:00 2001 From: metif12 Date: Sat, 10 Oct 2026 15:51:15 +0330 Subject: [PATCH 10/29] docs, examples: the json2 zero-decode bug no longer reproduces, and the .d.ts are regenerated The machine's compiler moved from `bb0d229` to `ef2ec06` during this session's work, and the bug this repository filed upstream stopped reproducing. Verified rather than assumed: the same reproduction across three fresh project roots prints `vails` correctly every time, `vails doctor` in examples/dialog reports `vails.json : ok`, and all three checked-in declarations now regenerate - which was the task the bug blocked in the first place. The three examples/*/frontend/vails.d.ts files were regenerated and gained the blocking-command JSDoc that services/dts.v has emitted since the previous commit. 11 added lines, no churn - their "do not edit" header is a rule about not hand-editing, not about not regenerating. AGENTS.md keeps the whole thing but corrects two explanations that were offered and then killed, which matter more than the shot in the dark they replaced: - "the _str_N literals collide" - refuted by a control: two programs differing only by an UNUSED `import sync` disagree on 507 of 2160 identical-index literals and both decode correctly. The statement in question is a zero-initialisation, and each build seeds it at its own string table's index. So index divergence is the normal state between two programs with different module sets and cannot be the cause. - "a module named `cfg` is special too" - it fails to build in the harness where every other name built, which looked like a sibling bug. It is the harness: `duplicate of an import symbol 'cfg'` is a VARIABLE named cfg colliding with `import cfg`. Decisive control: a module named `zzz` with a variable `zzz` fails identically, and module `cfg` with the variable renamed decodes fine. It also records that a V maintainer closed the upstream report `completed` (2026-10-05) BEFORE the non-reproduction here was measured, so the fix is confirmed at the source rather than inferred from my own negative result, and that which of nine json2 commits fixed it is not bisected and must not be attributed. buildplan/json2_import_test.v is unchanged and stays: it is about this repository's test layout, not about V. 45/45 on both platforms here and in CI; the Linux job goes from RED on main to green on this branch. Note for whoever reads this next: the `vails` CLI only works because V moved. If the compiler regresses or a new module imports net.http, the guard goes red at review time now rather than at `vails doctor` time. --- AGENTS.md | 104 ++++++++++++++++---------- ROADMAP.md | 22 +++--- examples/dialog/frontend/vails.d.ts | 3 + examples/services/frontend/vails.d.ts | 4 + examples/showcase/frontend/vails.d.ts | 4 + 5 files changed, 87 insertions(+), 50 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1e46bd1..bf0e2b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -165,29 +165,35 @@ main.v -> import json2 / import os / import net.http / import config data.json -> {"name": "vails", "n": 3} ``` -A lead on the cause, recorded because it is cheap and offered as a **hypothesis, -not a diagnosis**: the failing and passing builds both emit - -```c -config__Cfg result = (config__Cfg){.name = _str_36}; -``` - -but define `_str_36` differently — `{"", 0, 1}` in the failing build, a long -unrelated `array.ensure_noscan` message in the passing one. So the same -`_str_N` index names different literals in the two programs, which is consistent -with a collision or a numbering computed over a differing module set. Nobody has -diffed the symbol tables yet. - -Also unchased, and deliberately not claimed: a module named **`cfg`** failed to -build three times in a row in the same harness where every other name built. - -**Consequence for this repository: the `vails` CLI cannot read `vails.json`.** -`vails doctor`, `vails run`, `vails build` and `vails dts` all report -`vails.json: name must not be empty` on a perfectly valid project. `dev/dev.v` -and `dev/serve.v` are the only `net.http` importers, `cli` imports `dev` for -`vails run`'s dev server, and this repository's config module is named `config` -— so all three conditions are met by construction, and that one import is the -whole exposure. +**Two explanations for it were offered and then killed, and the kills matter more +than the shot in the dark they replaced.** + +*Lead 1 — "the `_str_N` literals collide."* Both failing and passing builds emit +`config__Cfg result = (config__Cfg){.name = _str_36};`, but at that index the +failing build defines `{"", 0, 1}` and the passing one a long unrelated +`array.ensure_noscan` message. It reads like a numbering collision. **It is +not.** Two programs that differ only by an unused `import sync` — both decoding +correctly — disagree on **507 of 2160 identical-index literals**, and the +statement in question is a *zero-initialisation*: both builds seed `name` with +the empty string at the index each string table happens to give it, which is +correct and internally consistent. So `_str_N` divergence is the normal state +between any two programs with different module sets and cannot be the cause. + +*Lead 2 — "a module named `cfg` is special too."* It looks special: it fails to +build where every other name built. It is not the same bug, and it is not a +compiler quirk. `error: duplicate of an import symbol 'cfg'` — a module named +`cfg` collides with a *variable* named `cfg`, because the struct is `Cfg` and a +local called `cfg` is the natural thing to write. The control is decisive: a +module named `zzz` with a variable `zzz` fails identically, and module `cfg` +with a variable renamed decodes fine. So this was the harness, not V. + +**Consequence for this repository, and note that it no longer applies:** the +`vails` CLI could not read `vails.json`. `vails doctor`, `vails run`, +`vails build` and `vails dts` all reported `vails.json: name must not be empty` +on a perfectly valid project. `dev/dev.v` and `dev/serve.v` are the only +`net.http` importers, `cli` imports `dev` for `vails run`'s dev server, and this +repository's config module is named `config` — so all three conditions were met +by construction, and that one import was the whole exposure. **Why `v test .` is 45/45 green and still cannot see this:** every `_test.v` file is its own binary, and **no test file links `dev` with `config`** @@ -197,22 +203,42 @@ cannot assert the bug, because a test that reproduces it would only pass while the compiler is broken — but no test here can catch a regression in the decode itself. This is the §2c lesson at suite scale: a green check that cannot fail. -Practical rules until this is fixed or filed: - -- Do not trust `config.load` (or any `json2.decode` in a module named `config`) - in a binary that also links `net.http`. `vails doctor` reaching - `vails.json : INVALID` is this bug, not a bad config. -- The check that matters is whether **the decoding module is named `config`** - and **its binary links `net.http`**. Neither condition alone does anything. -- Anything that must read `vails.json` outside a test belongs in a module that - does not import `dev`. -- The checked-in `examples/*/frontend/vails.d.ts` files cannot be regenerated - with `vails dts` for this reason; they were last generated before the move to - master and say so in their header ("do not edit"). - -Upstream: [vlang/v#29508](https://github.com/vlang/v/issues/29508). Note that -master has moved past the compiler this was measured on (`bb0d229` → `3c5f448`) -and the fix is not ours to make. +**It no longer reproduces. Re-measured 2026-10-10 on V master `ef2ec06`** — the +same program, three fresh project roots, prints `vails` correctly every time, and +`vails doctor` in `examples/dialog` reports `vails.json : ok`. So the trigger +above is a description of a compiler state, not of the compiler. Nine `json2` +commits landed between the two builds, among them `json2: cache compact ASCII +struct keys (#29701)` and `json2: skip unused key tracking for structs without +embeds (#29656)`; **which one fixed it is not bisected**, so do not attribute it. + +What survives, because it is about this repository and not about V: + +- The `vails` CLI reads `vails.json` again, and the three + `examples/*/frontend/vails.d.ts` files were regenerated on 2026-10-10 and now + carry the blocking-command JSDoc. Their headers still say "do not edit", + which is a rule about not hand-editing, not about not regenerating. +- `buildplan/json2_import_test.v` stays. It asserts that `net.http` keeps one + importer, that this importer and every `json2.decode` instantiator stay + **disjoint**, and that `cli` is where the two meet — which is exactly the + shape that made the bug reachable here. A regression in V would make that + workbook again, and the guard is what makes the next one visible at review + time instead of at `vails doctor` time. +- The general lesson is the one that generalises: **the suite was 45/45 green + while a shipped command was broken**, because no test binary linked `dev` + with `config`. That is not a V bug, it is a property of this repo's test + layout, and it is still true. + +Upstream: [vlang/v#29508](https://github.com/vlang/v/issues/29508). A V +maintainer closed it **`completed` on 2026-10-05**, before the non-reproduction +above was measured, so the fix is confirmed at the source and not merely +inferred here. The report was updated on 2026-10-10 with the non-reproduction, +the two retracted claims, and the candidate commits — with the retractions at +the top rather than buried, because the first version of that report is what a +maintainer's afternoon would have gone on. + +The compiler that **did** reproduce was `bb0d229` (measured 2026-10-05), which +no longer exists as a binary on this machine. Master has since moved to +`3c5f448` and then `ef2ec06`. #### Two history worth keeping, because both cost an afternoon diff --git a/ROADMAP.md b/ROADMAP.md index be1e50d..cc5477a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -16,7 +16,7 @@ an ADR, not here. | `v test .` on Linux | **45/45 test files green** — measured 2026-10-05 in the CI container, the first time this had ever been run. It began at **20 of 44 failing**, for three root causes: `services` did not compile at all (`drop.v` named the Windows-only `read_dropped_paths_native` from platform-neutral code), `webview_linux.c.v` had 7 compile errors from the F0 multi-window work, and `jobs_test.v` asserted a Windows-only error string. The `webview` files **run** here too — which was the point of this row while Windows could not run them, and is no longer a differentiator. | | Current phase | **Phase 5** (services) — S1 waves 1–4 and Phase 5b shipped | | Next by the table | **the Linux suite is green** (below). Next: F1, then W1–W4 | -| **Build-blocked on** | **`vails.json` cannot be loaded by the built CLI** - a V master bug, not a Vails bug. Found 2026-10-05, not yet filed upstream. See below. | +| **Build-blocked on** | *nothing. The `vails.json` blocker that sat here on 2026-10-05 was a V master bug and stopped reproducing once V moved to `ef2ec06`; AGENTS.md §1b records the whole thing, including why the guard stays.* | | Runtime-blocked on | a display session for the Linux GUI proofs, a macOS backend (Phase 6) | **THE CLI CANNOT READ `vails.json`, AND `v test .` CANNOT SEE IT.** Found @@ -57,16 +57,16 @@ Three things worth remembering about it: `_test.v` is its own binary and **no test file imports both `dev` and `config`**. Same lesson as `workflow_test.v` and `bom_test.v`, one level up: the suite is green and the property it appears to cover is exercised nowhere. -- **It is upstream.** `json2` was three days old on `vlang/v` master - (2026-10-03) and this needs an unusual combination to bite, so the fix is a V - bug report, not a Vails patch. Filed as [vlang/v#29508](https://github.com/vlang/v/issues/29508), - with the module-name sweep as the evidence. Note that master has already moved - past the compiler this was measured on (`bb0d229` → `3c5f448`) and none of the - five intervening commits touch `vlib/json2`, so the report asks for - re-confirmation rather than claiming current-master breakage. The workaround - that would unblock the CLI is to keep `net.http` out of the binary that reads - config, which means `vails run` spawning a separate helper process — a real - restructure, not done. +- **It is upstream, and it is gone.** `json2` was three days old on `vlang/v` + master when this bit. Filed as + [vlang/v#29508](https://github.com/vlang/v/issues/29508) with the module-name + sweep as the evidence; **closed as fixed**, because on 2026-10-10 the same + program on V master `ef2ec06` decoded correctly and `vails doctor` reported + `vails.json : ok` again. Nine `json2` commits landed between the two builds + and **which one fixed it was never bisected**, so do not attribute it. The + guard in `buildplan/json2_import_test.v` stays regardless, because it is + about this repository's test layout: it makes the next one visible at review + time rather than at `vails doctor` time. **CI NOW RUNS JOBS.** On 2026-10-05 this stopped being a claim. Two distinct causes had been producing the identical "0s, zero jobs" symptom, and only the diff --git a/examples/dialog/frontend/vails.d.ts b/examples/dialog/frontend/vails.d.ts index b1acf31..71b08f3 100644 --- a/examples/dialog/frontend/vails.d.ts +++ b/examples/dialog/frontend/vails.d.ts @@ -10,8 +10,11 @@ export namespace dialog { export interface DialogMessageResult { canceled: boolean; paths: string[]; button: string; } export const service: string; export const version: string; + /** open blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function open(params: DialogOpenOptions): Promise; + /** save blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function save(params: DialogSaveOptions): Promise; + /** message blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function message(params: DialogMessageOptions): Promise; } export namespace os_info { diff --git a/examples/services/frontend/vails.d.ts b/examples/services/frontend/vails.d.ts index c9d54c4..261d251 100644 --- a/examples/services/frontend/vails.d.ts +++ b/examples/services/frontend/vails.d.ts @@ -37,6 +37,7 @@ export namespace menu { export interface MenuCanceled { canceled: true; } export const service: string; export const version: string; + /** popup blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function popup(params: MenuPopup): Promise; export function close(params: undefined): Promise; export function set_menu(params: MenuPopup): Promise; @@ -50,8 +51,11 @@ export namespace dialog { export interface DialogMessageResult { canceled: boolean; paths: string[]; button: string; } export const service: string; export const version: string; + /** open blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function open(params: DialogOpenOptions): Promise; + /** save blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function save(params: DialogSaveOptions): Promise; + /** message blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function message(params: DialogMessageOptions): Promise; } export namespace tray { diff --git a/examples/showcase/frontend/vails.d.ts b/examples/showcase/frontend/vails.d.ts index 43682b1..f5a55ee 100644 --- a/examples/showcase/frontend/vails.d.ts +++ b/examples/showcase/frontend/vails.d.ts @@ -37,6 +37,7 @@ export namespace menu { export interface MenuCanceled { canceled: true; } export const service: string; export const version: string; + /** popup blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function popup(params: MenuPopup): Promise; export function close(params: undefined): Promise; export function set_menu(params: MenuPopup): Promise; @@ -50,8 +51,11 @@ export namespace dialog { export interface DialogMessageResult { canceled: boolean; paths: string[]; button: string; } export const service: string; export const version: string; + /** open blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function open(params: DialogOpenOptions): Promise; + /** save blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function save(params: DialogSaveOptions): Promise; + /** message blocks the UI until it is answered (a native modal). Do not call it from a loop or a startup path; it is the documented exception to the "handlers must be fast" threading rule (ADR-0014). */ export function message(params: DialogMessageOptions): Promise; } export namespace tray { From 523ab8da7bfcd1585b830cb70f543f1a3ad970a0 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sat, 10 Oct 2026 16:20:57 +0330 Subject: [PATCH 11/29] docs: the accuracy pass reaches ROADMAP.md, and ADR-0038 records its caller The first pass fixed `README.md`, `AGENTS.md` and the two dated ADRs, and left the file that states this project's position half-updated. `ROADMAP.md` carried four claims that had been overtaken, and every one of them under-stated what the repository now does - which is the more dangerous direction, because an under-claim that is never revisited becomes an instruction. - *"`menu.png` / `tray.png` / `dialog.png` exist"* - `git log --all` returns zero commits for all three. The errata went on the ADRs that cited them; this file was still telling the reader they exist. - *"the runner has still never reported a single green job"* - the Linux container job passes, and the branch this sits on is what took it there. - *"this machine crashes its host on the `webview` test module"* - all six files compile AND run, twice, at 45/45, on the same compiler both measurements were taken against and with no test edited to make them pass. Recorded as history and labelled *currently green* rather than *fixed*, because what changed is not known: a claim with no known cause should not be restated without its history. - the priority table called F1 drag & drop "planned" - it landed as ADR-0036 on 2026-10-03. The next unwritten row is W1-W4, and it needs two platforms of native C interop plus a human to drag a window edge, so it is now said out loud rather than left implicit. The `Where we are` date moves to 2026-10-10 with the above. ADR-0038 gains a dated implementation note rather than a rewrite, matching the convention the other dated ADRs were given. Three things are in it, and the middle one is the reason it is worth writing down: an unset `VAILS_TOOLCHAIN` prints the byte-identical header path as before, a *set* one no longer reports the default root as healthy, and the `#flag` half is still unwritten and still uncompiled. The note also corrects this ADR's own Context, which counts `cli/vails.v` as one of four hard-coded sites and no longer should. No code changed; 45/45 on Windows and in the Linux container. --- CHANGELOG.md | 34 +++++++++++++++ ROADMAP.md | 55 ++++++++++++++----------- docs/ADR/0038-windows-toolchain-root.md | 47 ++++++++++++++++++++- 3 files changed, 111 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 834a2f6..451d1d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,40 @@ Conventions for this file: ### Changed +- **The `json2` zero-decode bug no longer reproduces, and the three `.d.ts` are + regenerated.** The compiler moved from `bb0d229` to `ef2ec06` while this branch + was open and the bug stopped reproducing — verified across three fresh project + roots, `vails doctor` reporting `vails.json : ok`, and `vails dts` regenerating. + The blocking-command JSDoc now reaches all three checked-in declarations + (11 added lines, no churn). `buildplan/json2_import_test.v` is unchanged: it is a + guard on this repository's test layout, and a second `net.http` importer goes red + at review time now rather than at `vails doctor` time. AGENTS.md 1b records the + whole thing, including **two explanations that were offered and then killed** — + the `_str_N` literal collision (refuted by a control: an *unused* `import sync` + changes 507 of 2160 identical-index literals and both programs decode + correctly) and "a module named `cfg` is special too" (refuted: it is a *variable* + named `cfg` colliding with `import cfg`; a module named `zzz` with a variable + `zzz` fails identically). +- **A documentation accuracy pass on the one file the last pass only partly + reached.** `ROADMAP.md` carried four claims that had been overtaken, and all four + under-stated what the project now does: + + - *"`menu.png` / `tray.png` / `dialog.png` exist"* — `git log --all` returns zero + commits for all three. ADR-0017 and ADR-0027 are where the citations were fixed; + this file had been left saying the screenshots exist. + - *"the runner has still never reported a single green job"* — the Linux container + job passes, and this branch is what took it there. + - *"this machine crashes its host on the `webview` test module"* — all six files + compile **and** run, twice, at 45/45, on the same compiler both measurements + were made against. Kept as history, labelled *currently green* rather than + *fixed*, because **what changed is not known**. + - the priority table called F1 drag & drop "planned" — it landed as ADR-0036 on + 2026-10-03. The next unwritten row is W1-W4. + + `ADR-0038` gains a dated implementation note rather than a rewrite: the resolver + now has a production caller (`vails doctor`), an unset `VAILS_TOOLCHAIN` prints + the byte-identical header path as before, a set one no longer reports the default + root as healthy, and the `#flag` half is still unwritten and still uncompiled. - **Documentation accuracy pass, 2026-10-05.** No behaviour changed; three documents no longer cite screenshots that have never existed in this repository. `git log --all` returns **zero commits** for `tests/e2e_windows/tray.png`, diff --git a/ROADMAP.md b/ROADMAP.md index cc5477a..83b487f 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -7,7 +7,7 @@ current position, then what has shipped, then the priority table that decides what happens next. Anything about *why* something took three attempts belongs in an ADR, not here. -## Where we are (2026-10-04) +## Where we are (2026-10-10) | | | |---|---| @@ -15,7 +15,7 @@ an ADR, not here. | `v test webview` on Windows | **green as of 2026-10-05** — all six `webview` files compile *and* run, twice, inside a full `v -cc gcc test .` (45/45). This contradicts the measurement recorded here until today: **"cannot be run: it takes the host down"**, measured 4× on 2026-09-30 and once more on 2026-10-03, one file at a time and as a directory, with no OOM in the Windows event log. **What changed is not known**: the tests needed no editing to pass, and the compiler is the same 0.5.2 master as both earlier measurements. So treat this as *currently green*, not *fixed* — if it starts taking the host down again, this row is the history and the F0 work since 2026-10-03 is the first thing to suspect. | | `v test .` on Linux | **45/45 test files green** — measured 2026-10-05 in the CI container, the first time this had ever been run. It began at **20 of 44 failing**, for three root causes: `services` did not compile at all (`drop.v` named the Windows-only `read_dropped_paths_native` from platform-neutral code), `webview_linux.c.v` had 7 compile errors from the F0 multi-window work, and `jobs_test.v` asserted a Windows-only error string. The `webview` files **run** here too — which was the point of this row while Windows could not run them, and is no longer a differentiator. | | Current phase | **Phase 5** (services) — S1 waves 1–4 and Phase 5b shipped | -| Next by the table | **the Linux suite is green** (below). Next: F1, then W1–W4 | +| Next by the table | **the Linux suite is green** (below) and F1 has landed (ADR-0036), so the next unwritten row is **W1–W4** — frameless window chrome plus a `window` service, 6 d. Note what W1–W4 needs: native C interop on two platforms and a human to drag a window edge, so it is not a session of work | | **Build-blocked on** | *nothing. The `vails.json` blocker that sat here on 2026-10-05 was a V master bug and stopped reproducing once V moved to `ef2ec06`; AGENTS.md §1b records the whole thing, including why the guard stays.* | | Runtime-blocked on | a display session for the Linux GUI proofs, a macOS backend (Phase 6) | @@ -191,19 +191,21 @@ code in this repo should read §2c before it is written. The repo's own rule (AGENTS.md §5) is that a line either names a proof or says it is unproven. The four things most likely to be over-read: -- **B2+B3 (Dockerfile + CI): the CI has now been RUN once, and it is fixed but - still unproven.** The "never executed" claim was true until 2026-10-03, when it - was executed on GitHub and reported **"No jobs were run"** — one step had lost - its indentation, so the workflow was invalid YAML and GitHub had no jobs to - run. Fixed, and `buildplan/workflow_test.v` now guards it (the guard was - confirmed **red on the broken file and green on the fixed one**, which is the - only way to know a guard guards). The runner has still never reported a single - green job, so "CI is green" remains a claim nobody can make: the first real run - may well stop at the `json2` smoke step, which exists precisely to turn a - confusing failure into a named one. -- **The Linux GUI proofs need a real session.** `menu.png` / `tray.png` / - `dialog.png` exist; the Linux `menu:clicked {id}` mapping does not, because Xvfb - has no window manager to deliver the click. +- **B2+B3 (Dockerfile + CI): the Linux job is green and the Windows one is not, + and neither of those is the same as "CI is green".** The "never executed" claim + was true until 2026-10-03. Since then the Linux container job has **passed + repeatedly** (5m36s on the branch in #1, after starting at 20 of 44 test files + failing); the Windows job **still fails**, at the step that checks whether the + runner's own V can build this repository at all — it installs a *released* V, + and no release has `json2`. So the accurate statement is "one of the two jobs is + green", and the more useful one is "the Linux suite is now proven on a clean + runner", which is something this file could not say before. +- **The Linux GUI proofs need a real session, and three of the screenshots this + file used to cite have never existed.** `git log --all` returns **zero commits** + for `tests/e2e_windows/tray.png`, `tests/e2e_windows/menu.png` and + `tests/e2e_linux/dialog.png`, yet ADR-0017 and ADR-0027 both cited them as their + evidence — the errata on those ADRs record it. The Linux `menu:clicked {id}` + mapping does not, because Xvfb has no window manager to deliver the click. - **`post_to_main` is Windows-only.** On Linux it refuses by name; the `g_idle_add` trampoline is unwritten, and it is the first push onto the GTK main loop from a foreign thread in this repo's history. @@ -230,14 +232,19 @@ is unproven. The four things most likely to be over-read: `Windows.winmd` or `UniversalApisContract.winmd`). Flipping that constant is the whole remaining work, and guessing a GUID instead would activate the wrong object. -- **F0's second Windows window is written and type-checked, not observed.** The - COM apartment that unblocks it is in `webview_windows.c.v` and `v vet webview` - is green, but **this machine crashes its host on the `webview` test module** — - measured three times on 2026-09-30, with one test file at a time and with the - whole directory, and with no OOM in the Windows event log, so the cause is - still unknown. Until somebody runs `examples/multiwindow` and puts two windows - in a screenshot, "multi-window works" is a claim. Every other module's tests - pass: 15 of 16 modules green on 2026-09-30, and `webview` is the sixteenth. +- **F0's second Windows window is written and type-checked, not observed** — and + the *reason* it was not observed has changed shape, so read the next paragraph + before repeating it. Until 2026-10-05 this entry said the `webview` test module + crashes the Windows host (measured three times on 2026-09-30, one file at a time + and as a directory, no OOM in the event log). On 2026-10-05 all six `webview` + test files compiled **and ran**, twice, inside a full `v -cc gcc test .` at + 45/45, on the same 0.5.2 master both measurements were taken against and with + no test edited to make them pass. **What changed is not known**, so treat this as + *currently green*, not *fixed* — it is recorded as history in the "Where we are" + table above, and F0's work since 2026-10-03 is the first thing to suspect if it + starts taking the host down again. The reason it is listed here anyway is the + part that did not change: nobody has run `examples/multiwindow` and put two + windows in a screenshot, so "multi-window works" is still a claim. ## Corrections worth remembering @@ -274,7 +281,7 @@ Effort is in focused days and is an estimate, not a commitment. | 6 | B0 | **B2+B3** Dockerfile + matrix CI | 4 d | P2–P4, B4 | the repo has no CI; `v test .` is green on both platforms already | **done, unproven (ADR-0034)** — no runner or container here | | 7 | — | **U0/W0** `post_to_main` | 3 d | U4–U7, W1–W4 | three dependents; also the job half of ADR-0019 (its subscriber half shipped as ADR-0023) | **done on Windows (ADR-0019)** — `jobs.v` + a real E2E screenshot; Linux `g_idle_add` deferred | | 8 | — | **F0** multi-window | 6 d | **W**, `tray.set_menu`, U4's second window | highest-leverage single item; reopens an ADR-0020 decision | **done, PROVEN on Windows (ADR-0035, 2026-10-04)** — 21 routing tests + a real two-window run that found two shipped bugs (`webview_dispatch` success read as failure, then an access violation inside the DLL); Linux structurally done, unrun | -| 9 | F0 | **F1** drag & drop | 6 d | R3 | the other platform gap; check `EnableWebDrop` reachability first | planned | +| 9 | F0 | **F1** drag & drop | 6 d | R3 | the other platform gap; check `EnableWebDrop` reachability first | **done, and the gating question is answered** (ADR-0036, 2026-10-03) - `EnableWebDrop` is **not reachable**: the installed `webview` 0.12 header exposes no `ICoreWebView2Controller`, so the design went to `WM_DROPFILES` on the HWND instead. The observable proof is the outstanding half: nothing has seen a human drag a file | | 10 | U0 | **W1–W4** chrome + `window` service | 6 d | the tutorial's menu item, E6 | absorbs S1 wave-4 `window-state`/`positioner` | planned | | 11 | W, F0 | **U1–U4** updater core + service | 8 d | U5, P4 | the manifest-as-core half is pure V and no I/O | planned | | 12 | B1–B4 | **P0–P4** distribution | 8 d | release | the update-channel policy is decision-only and independent | planned | diff --git a/docs/ADR/0038-windows-toolchain-root.md b/docs/ADR/0038-windows-toolchain-root.md index e9f551a..2f79228 100644 --- a/docs/ADR/0038-windows-toolchain-root.md +++ b/docs/ADR/0038-windows-toolchain-root.md @@ -1,7 +1,9 @@ # ADR-0038 — the Windows toolchain becomes a resolved root, and MSVC stops at the webview boundary Date: 2026-10-03. Status: **accepted; the resolver is written, the `#flag` half is -blocked and named.** +blocked and named.** *(2026-10-10: the resolver now has a production caller — see +the implementation note at the end of this file. The `#flag` half is still not +written.)* ## Context @@ -135,3 +137,46 @@ part that needs no compiler trick: the resolver. was left unwritten rather than written blind: a generated-header mechanism that has never been through a compiler is exactly the "GTK C nobody has run" mistake ADR-0015 exists to prevent. + +## Implementation note, 2026-10-10 + +The resolver has a production caller now, so this ADR's status moves one notch and +the record should say which notch. The Changes are additive and in the order the +Consequences listed them. + +**`vails doctor` uses `buildplan.resolve_toolchain()`** instead of asserting +`C:/msys64/ucrt64/include/webview/webview.h`. The `webview` line checked a literal, +so a machine with a relocated or scoped toolchain was told about the one root that +cannot be the answer — and, worse, an explicitly *set* `VAILS_TOOLCHAIN` pointing at +an existing directory would still be reported as the default root, because the +literal never changed. Now the header is looked up under the resolved root, and the +missing pieces (`webview.h`, `libwebview.dll.a`, the `bin` directory holding the +five side-by-side DLLs) are listed together rather than surfacing one at a time +**three minutes into a build**, which is the failure mode ADR-0035's own COM +apartment story is about. + +Measured, because the claim above is only worth as much as its evidence: + +- an unset `VAILS_TOOLCHAIN` prints the **byte-identical** header path as before, + because the default *is* that root — so this is not a behaviour change on a + healthy machine; +- with `VAILS_TOOLCHAIN` pointed at `D:/does/not/exist`, `doctor` prints + `toolchain : D:/does/not/exist (from VAILS_TOOLCHAIN)` and three specific + missing-piece notices, where the old code printed + `webview : header found (C:/msys64/ucrt64/…)`. +- the `side-by-side` DLL line **deliberately still uses `buildplan.ucrt64_bin`**, + whose own comment records that it matches the webview backend's `#flag -I/-L`. + Following the variable there would stage DLLs from one toolchain next to a binary + built against another, which is the exact mismatch `ucrt64_bin` warns about. + +**Still not done, and this note is not a claim that it is:** the `#flag` half. The +generated-header mechanism described above has never been compiled here, and the +Verification section's "not compiled" line below it is still true of that half. +`webview_windows.c.v` keeps its literal `-I`/`-L`, so a *scoped* toolchain still +cannot be used to build a GUI target without the resolved root happening to be the +MSYS2 default. + +One editorial correction to this ADR's own Context: it says `cli/vails.v` is one of +four places that hard-code the path. After this change it is no longer one of them, +so the count is **three**, and this paragraph is that correction rather than a +rewrite of the table above. From 8fd1586eac87af4cc4aa36d5f3e32eb22c2e5835 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sat, 10 Oct 2026 17:12:39 +0330 Subject: [PATCH 12/29] Dockerfile: pin the V commit, because a cached layer silently chose the compiler The V layer cloned whatever master pointed at on the day it was first built and never rebuilt - a cached layer is content-addressed, so every later build reused that one V while the host moved on. Measured on 2026-10-10: the image carried V e5ab344, five days stale, and master was already 60542b9. The consequence was real and invisible from the test output. The stale V still had the `config` + `net.http` zero-decode defect (AGENTS.md 1b - a module named `config` plus `net.http` in one binary decodes to a zero struct with no error), so inside this container `vails doctor` reported `vails.json : INVALID` for a project whose config is valid, **on a suite that was 45/45 green**. The same program on the host decoded correctly. Nothing in the output could tell the two compilers apart, which is the whole danger: the cache chooses which compiler you are testing against and does not announce it. Verified both directions with the same program in one container - `WITHHTTP name=[]` and `NOHTTP name=[vails]` on the stale V, `vails` for both on the pinned one. V is now pinned to a commit, fetched by full sha (a short sha is refused by GitHub), with the measured failure and the bump procedure written into the file. Pinning also gives this file the property its own header argues for in point 3 and had left unapplied to V: an unpinned ref can change under a fixed name, which makes a green run meaningless. `services/dialog_support` stopped lying about the Linux dialog in the same pass, because this is the container that exposed it. It answered `stub: the GTK chooser lands in Phase 5b` on Linux for two releases after Phase 5b landed the real backend, so `doctor` said `stub dialog`, `5/9 backends native`, on a machine with GtkFileChooserDialog compiled in and its response mapping tested. `support_test.v:67` was pinning the opposite assertion, with a comment calling dialog "still the GTK stub", so the stale line stayed green the whole time - the 2c failure at service scale, a test that asserts something false. Both are fixed, and the new assertions pin the *content* of the note rather than the `ready` flag alone: `ready` and `GtkFileChooserDialog` present, `stub` absent. Seen red by planting the stub string back on Linux (`assert dialog_support().ready` failed), then green on restore - which is also the first time this container has been used to turn a Windows-only check red rather than green, and the reason it was worth building it. Linux `doctor` now reports 6/9 backends native and `vails.json : ok`. 45/45 on both platforms. --- CHANGELOG.md | 32 ++++++++++++++++++++++++++++++++ Dockerfile | 35 +++++++++++++++++++++++++++++++++-- services/dialog.v | 16 +++++++++++----- services/support_test.v | 14 +++++++++++--- 4 files changed, 87 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 451d1d4..bbb27c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,38 @@ Conventions for this file: ### Changed +- **The Dockerfile's V layer was five days stale, and that is why the json2 bug + "came back" on Linux.** The layer cloned whatever master pointed at on the day + it was first built and then never rebuilt, because a cached layer is content- + addressed: every later `docker build` reused a V from 2026-10-05 while the host + moved on. Measured 2026-10-10: the image carried V `e5ab344` while the Windows + host ran `ef2ec06`. The stale V still had the `config` + `net.http` zero-decode + defect (AGENTS.md §1b), so in the container `vails doctor` reported + `vails.json : INVALID` **on a suite that was 45/45 green**, while the same + command on the host reported `ok`. Nothing in the test output could tell the + two compilers apart, which is the whole danger: the cache chooses which + compiler you are testing against and does not announce it. V is now pinned to a + commit, fetched by full sha (a short sha is refused by GitHub), with the + measured failure and the bump procedure in the Dockerfile. Pinning also gives + this file the property its own header argues for in point 3 and had left + unapplied to V — an unpinned ref can change under a fixed name, which makes a + green run meaningless. +- **`vails doctor` stopped lying about the Linux dialog, and the test that kept + it quiet is fixed too.** `dialog_support()` answered `stub: the GTK chooser + lands in Phase 5b` on Linux for two releases after Phase 5b landed the real + backend (ADR-0027) — so `doctor` said `stub dialog`, `5/9 backends native`, on + a machine with `GtkFileChooserDialog` compiled in and its response mapping + tested. `services/support_test.v:67` was pinning the opposite assertion, with a + comment saying dialog "is still the GTK stub", so the stale line was green the + whole time. That is the §2c failure at service scale: a test that asserts + something false. Both are fixed, and the new assertions pin the *content* of the + note — `ready` and `GtkFileChooserDialog` present, `stub` absent — so the stub + cannot come back without a red test. Linux `doctor` now reports + `6/9 backends native, ok dialog - GtkFileChooserDialog + GtkMessageDialog`. + Seen red by planting the stub string back on Linux + (`assert dialog_support().ready` failed), then green on restore — which is also + the first time the container has been used to turn a Windows-only check red. + - **The `json2` zero-decode bug no longer reproduces, and the three `.d.ts` are regenerated.** The compiler moved from `bb0d229` to `ef2ec06` while this branch was open and the bug stopped reproducing — verified across three fresh project diff --git a/Dockerfile b/Dockerfile index cc591d6..0818806 100644 --- a/Dockerfile +++ b/Dockerfile @@ -76,9 +76,40 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ net-tools \ && rm -rf /var/lib/apt/lists/* -# V from source, as a cached layer (see the header). +# V from source, as a cached layer (see point 2 in the header). +# +# **The commit is pinned, and this is a fix for a measured failure rather than +# tidiness.** This line used to clone whatever master pointed at on the day the +# layer was *first* built, and then never rebuild: a cached layer is content- +# addressed, so every later build reused a V from that day while the host moved +# on. Measured on 2026-10-10, the image carried V `e5ab344` (five days stale, +# master was `60542b9`) while the Windows host ran `ef2ec06`. +# +# The consequence was concrete, and invisible from the test output: the stale V +# still had a `json2` defect the host's had fixed (AGENTS.md §1b — a module named +# `config` plus `net.http` in one binary decodes to a zero struct with no error). +# So in this container `vails doctor` reported `vails.json : INVALID` on a project +# whose config is valid, on a suite that was **45/45 green**. The same program +# decoded correctly on the host. Nothing in the test output could tell the two +# compilers apart, which is what makes a cached toolchain dangerous: the cache +# decides which compiler you are testing against, and it does not announce it. +# +# Pinning also gives this file the property it argues for in point 3 above: an +# unpinned ref can change its contents under a fixed name, which makes a green +# run meaningless. That argument was made for the base image and left unapplied +# to V, which is the thing that actually decides the test results. +# +# **Bump V_SHA deliberately.** Fetching by full sha works on GitHub for any +# reachable commit; a *short* sha is refused ("couldn't find remote ref"). +# Verify against the current master (`gh api repos/vlang/v/commits/master`) +# before bumping, and re-run the container's `vails doctor` after, because the +# failure mode above is silent. +ARG V_SHA=ef2ec067e09e006f6427ccdfb871fe6eea572823 WORKDIR /opt/vlang -RUN git clone --depth 1 https://github.com/vlang/v.git . \ +RUN git init -q . \ + && git remote add origin https://github.com/vlang/v.git \ + && git fetch --depth 1 origin $V_SHA \ + && git checkout -q FETCH_HEAD \ && make \ && ./v version diff --git a/services/dialog.v b/services/dialog.v index 3d4b96c..65da2bc 100644 --- a/services/dialog.v +++ b/services/dialog.v @@ -451,9 +451,15 @@ pub fn install_dialog(mut router bridge.Router, ctx webview.Ctx) ! { } // dialog_support answers "can this platform show a file picker?" (see -// support.v). The Linux half is still a stub even though the toolchain now -// exists: the GTK chooser is the last S1 item waiting on a human answering a -// modal window, and it is scheduled in Phase 5b. +// support.v). +// +// This function used to say the Linux half was a stub and scheduled it in +// Phase 5b. Phase 5b then landed the backend (ADR-0027, `dialog_linux.c.v`), +// and this line was not updated - which made `vails doctor` report +// `stub dialog` on a machine with a real GTK chooser compiled in and tested, +// for two releases. `support_test.v` pinned it, so nothing failed. A green +// check asserting something false is the §2c failure at service scale, and the +// reason the note now names the backend rather than a phase. pub fn dialog_support() ServiceStatus { $if windows { return ServiceStatus{ @@ -464,8 +470,8 @@ pub fn dialog_support() ServiceStatus { } $else $if linux { return ServiceStatus{ name: 'dialog' - ready: false - note: 'stub: the GTK chooser lands in Phase 5b' + ready: true + note: 'GtkFileChooserDialog + GtkMessageDialog (gtk_dialog_run spins a nested main loop - the ADR-0014 blocking exception, so a handler may park here)' } } $else { return ServiceStatus{ diff --git a/services/support_test.v b/services/support_test.v index 14d350d..6c0f4c1 100644 --- a/services/support_test.v +++ b/services/support_test.v @@ -60,11 +60,19 @@ fn test_support_matches_the_dispatch_branch() { assert opener_support().ready assert dialog_support().ready } $else $if linux { - // clipboard and opener got real backends in wave 2; dialog is still - // the GTK stub and notification has no backend at all + // clipboard and opener got real backends in wave 2, and dialog's GTK + // backend landed with Phase 5b (ADR-0027). This branch used to assert + // `!dialog_support().ready`, with a comment calling dialog "still the + // GTK stub", because dialog_support() itself said so - and both were + // stale. The note is asserted rather than the stub string, so the + // stub cannot come back without a red test: `doctor` reporting + // `stub dialog` on a machine with a real chooser is the over-read + // AGENTS.md 5 exists to prevent. assert clipboard_support().ready assert opener_support().ready - assert !dialog_support().ready + assert dialog_support().ready + assert !dialog_support().note.contains('stub') + assert dialog_support().note.contains('GtkFileChooserDialog') assert !notification_support().ready assert !is_supported() } $else { From 75aa12970f4e90a8448c7df565cb0ca3c0811db1 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sat, 10 Oct 2026 18:36:36 +0330 Subject: [PATCH 13/29] Dockerfile: move the V pin to 60542b9, because a green suite hid the first pin's linker bug The first pin (`ef2ec06`) was verified against one thing and one thing only: that it had the `json2` fix. It did. It also emits undefined reference to `closure__closure_try_destroy` from `vlib/os`'s `execve` / `execvp` paths, twice per suite run. V recovers on its own, so the summary still reported **45/45 passed** - the cache-staleness trap one layer down, where a green run hides a broken compiler instead of hiding which compiler you tested against. Caught it by grepping a run for `collect2` and `undefined reference` rather than reading the summary line. `10a210b` ("modulecache: own constants and emit cached declarations on demand") landed after it and is the likely fix. Moved the pin to `60542b9`, current master, and verified all three things instead of one: 1. the `json2` repro decodes correctly with and without `net.http` 2. no linker errors anywhere in a full `v test .` - grepped, not assumed 3. 45/45 The Dockerfile's bump procedure now names the regression and says to grep, because "the suite is green" is what let the first pin look verified. Both of the commits this file has pinned ran 45/45; only one of them worked. In the same pass, `drop`'s Linux half stopped justifying itself with a reason that has expired. `drop_linux.c.v` and `drop_support()` still said "this machine has no Linux runner", which was true when written and stopped being true on 2026-10-05: this Dockerfile builds a pinned V from source, runs 45/45 with GTK C compiled in, and `run_headless.sh` runs a real app under Xvfb. All three places now say the remaining gap is the code and not the ability to prove it. A stale reason reads as a blocker, and a next person does not start. No production code changed - comments, a status note, a ROADMAP line and the pin. 45/45 on Windows and in the Linux container; fmt and encoding clean. --- CHANGELOG.md | 22 ++++++++++++++++++++++ Dockerfile | 32 ++++++++++++++++++++++++++------ ROADMAP.md | 15 ++++++++++----- services/drop.v | 24 +++++++++++++++--------- services/drop_linux.c.v | 24 +++++++++++++++++------- 5 files changed, 90 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bbb27c1..a11a162 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,28 @@ Conventions for this file: ### Changed +- **The V pin moved to `60542b9`, because the first pin carried a Linux linker + regression that a green suite hid.** `ef2ec06` was the first pin and it was + right about the `json2` defect — but it emits `undefined reference to + closure__closure_try_destroy` from `vlib/os`'s `execve`/`execvp` paths, twice + per suite run. V recovers on its own, so **the summary still said 45/45**, which + is the cache-staleness trap one layer down: a green run that hides a broken + compiler. `10a210b` ("modulecache: own constants and emit cached + declarations on demand") landed after it and is the likely fix; verified on this + commit — the `json2` repro decodes correctly both ways, **no linker errors + anywhere in the run**, and `vails doctor` reports `vails.json : ok`. The + Dockerfile now names the regression, and the bump procedure says to grep for + `collect2` / `undefined reference` rather than trusting the summary line. +- **`drop`'s Linux half is the last deliberate stub, and its stated reason for + being one expired.** `drop_linux.c.v` and `drop_support()` both said "this + machine has no Linux runner", and that stopped being true on 2026-10-05: the + Dockerfile builds a pinned V from source, runs the suite 45/45 green **with GTK + C compiled in**, and `run_headless.sh` runs a real app under Xvfb. Both files, + and the ROADMAP's `drop` line, now say the gap is the code and not the ability + to prove it — recorded rather than left inherited, because a stale reason reads + as a blocker and the next person does not start. The support note still says + `unwritten` rather than `unsupported`, because those are different claims. + - **The Dockerfile's V layer was five days stale, and that is why the json2 bug "came back" on Linux.** The layer cloned whatever master pointed at on the day it was first built and then never rebuilt, because a cached layer is content- diff --git a/Dockerfile b/Dockerfile index 0818806..5a448da 100644 --- a/Dockerfile +++ b/Dockerfile @@ -82,8 +82,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # tidiness.** This line used to clone whatever master pointed at on the day the # layer was *first* built, and then never rebuild: a cached layer is content- # addressed, so every later build reused a V from that day while the host moved -# on. Measured on 2026-10-10, the image carried V `e5ab344` (five days stale, -# master was `60542b9`) while the Windows host ran `ef2ec06`. +# on. Measured on 2026-10-10, the image carried V `e5ab344`, five days stale, +# against a host at `ef2ec06` and a master at `60542b9`. # # The consequence was concrete, and invisible from the test output: the stale V # still had a `json2` defect the host's had fixed (AGENTS.md §1b — a module named @@ -94,6 +94,22 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # compilers apart, which is what makes a cached toolchain dangerous: the cache # decides which compiler you are testing against, and it does not announce it. # +# **The first pin was `ef2ec06`, and it was wrong for a measure I had not taken: +# it carries a Linux linker regression.** `undefined reference to +# closure__closure_try_destroy` from `vlib/os`'s `execve`/`execvp` paths, twice +# per suite run. V recovers by itself, so the suite still reports 45/45 — which is +# exactly the trap above, one layer down: a green run that hides a broken compiler. +# `10a210b` ("modulecache: own constants and emit cached declarations on demand") +# landed after it and is the likely fix, so the pin moved to `60542b9`, which is +# also current master. Verified on this commit: the `json2` repro decodes +# correctly both ways, **no linker errors anywhere in the run**, and +# `vails doctor` reports `vails.json : ok`. +# +# **A green suite is not a compiler check.** Both of the pins above ran 45/45, +# and one of them had a linker bug. The check worth adding to any bump is the +# container's `grepped` output for `collect2` / `undefined reference`, not the +# summary line. +# # Pinning also gives this file the property it argues for in point 3 above: an # unpinned ref can change its contents under a fixed name, which makes a green # run meaningless. That argument was made for the base image and left unapplied @@ -101,10 +117,14 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # # **Bump V_SHA deliberately.** Fetching by full sha works on GitHub for any # reachable commit; a *short* sha is refused ("couldn't find remote ref"). -# Verify against the current master (`gh api repos/vlang/v/commits/master`) -# before bumping, and re-run the container's `vails doctor` after, because the -# failure mode above is silent. -ARG V_SHA=ef2ec067e09e006f6427ccdfb871fe6eea572823 +# Before bumping, check current master (`gh api repos/vlang/v/commits/master`), +# then verify all three things in the container rather than one: +# 1. `vails doctor` reports `vails.json : ok` (the `json2` defect) +# 2. no `collect2` / `undefined reference` in a full `v test .` (the closure +# regression) — grep for it; the summary line will not tell you +# 3. 45/45, obviously +# The first two are the failure modes that stayed green while being broken. +ARG V_SHA=60542b9904a3a0102575ec1104e548996f650a83 WORKDIR /opt/vlang RUN git init -q . \ && git remote add origin https://github.com/vlang/v.git \ diff --git a/ROADMAP.md b/ROADMAP.md index 83b487f..c506914 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1257,11 +1257,16 @@ a small platform nicety, or a non-goal with a reason attached. - **Paths, never contents.** A page that wants a file's bytes has to be given a way to ask; that capability should be granted on its own rather than inherited by every window that can receive a drop. - - **Linux is unwritten on purpose** (AGENTS.md §3.4, ADR-0015's lesson: no - native code that has never been compiled, and there is no Linux runner - here). Everything that is not native is done and tested; the gap is a - `GtkDropTarget` and one function. `doctor` says "unwritten", not - "unsupported", because only one of those is true. + - **Linux is unwritten on purpose** (ADR-0015's lesson: no native code that has + never been compiled). Everything that is not native is done and tested; the + gap is a `GtkDropTarget` and one function. `doctor` says "unwritten", not + "unsupported", because only one of those is true. **The reason for leaving it + unwritten has expired**, which is why this line is corrected rather than left: + it used to add "and there is no Linux runner here", and on 2026-10-10 that is + false — `Dockerfile` builds a pinned V from source and runs the whole suite + 45/45 green with GTK C compiled in, and `run_headless.sh` runs a real app + under Xvfb. So the remaining gap is the code and not the ability to prove it, + and `drop_linux.c.v`'s header now says so. - **Still unchecked, and for the same reason as F0**: nothing has seen a human drag a file, because the Windows GUI proofs go through the `webview` module that crashes this host. The outstanding run is the six-step procedure in diff --git a/services/drop.v b/services/drop.v index 3cf1295..017105c 100644 --- a/services/drop.v +++ b/services/drop.v @@ -339,18 +339,24 @@ pub fn drop_support() ServiceStatus { 'WebView2 child' } } $else $if linux { - // Not a stub by accident: the GTK half is a GtkDropTarget on the window, - // and writing GTK C that has never been compiled is how the wave-3 Linux - // build broke for four ordinary reasons while being blamed on V - // (ADR-0015). The pure-V half - the bounds, the payload, the policy - - // is written and tested on both platforms, so only the native read is - // missing. + // Not a stub by accident, and **not blocked any more either**. This branch + // used to justify itself with "this machine has no Linux runner", and that + // expired on 2026-10-05: `Dockerfile` builds a pinned V from source and runs + // 45/45 green with GTK C compiled in, and + // `tests/e2e_linux/run_headless.sh` runs a real app under Xvfb. So the + // honest statement is now only that the half is unwritten - the environment + // to write it against exists. + // + // The pure-V half - the bounds, the payload, the policy - is written and + // tested on both platforms, so only the native read is missing. + // `drop_linux.c.v` says the same at the file level, including what the + // pinned toolchain means for anyone who does write it. return ServiceStatus{ name: 'drop' ready: false - note: 'the GTK drop-target half is unwritten (no GtkDropTarget yet - ' + - 'ADR-0015 lesson: no native code that has never compiled); the ' + - 'bounds, the payload and the policy are done' + note: 'the GTK drop-target half is unwritten (one function of C - a ' + + 'GtkDropTarget on the toplevel reading text/uri-list); the bounds, ' + + 'the payload and the policy are done and tested here' } } $else { return ServiceStatus{ diff --git a/services/drop_linux.c.v b/services/drop_linux.c.v index 0d5cfe1..4a216cc 100644 --- a/services/drop_linux.c.v +++ b/services/drop_linux.c.v @@ -1,13 +1,23 @@ // drop_linux.c.v - Linux backend of the drop service: **unwritten on purpose**. // Compiled on Linux ONLY (V `_linux` suffix rule). // -// The GTK half would be a `GtkDropTarget` on the window, reading -// `drag-data-received` / `dropped-data` and turning `text/uri-list` into paths. -// It is not written here, and the reason is the one AGENTS.md §2 asks to be -// explicit about: **no native code that has never been compiled.** The wave-3 -// Linux build broke for four ordinary GTK reasons while being blamed on V -// (ADR-0015), and this machine has no Linux runner, so a `GtkDropTarget` written -// today would be GTK nobody has run. +// The GTK half is a `GtkDropTarget` on the window, reading `drag-data-received` / +// `dropped-data` and turning `text/uri-list` into paths. +// +// **The reason this file is still empty expired on 2026-10-05, and it is +// recorded here precisely so nobody keeps inheriting it.** This header used to +// say "this machine has no Linux runner, so a `GtkDropTarget` written today +// would be GTK nobody has run" - which was true when written, and is now false: +// `Dockerfile` builds V from source and runs the **whole suite, 45/45 green, +// with GTK C compiled in**, and `tests/e2e_linux/run_headless.sh` runs a real app +// under Xvfb and screenshots it. So the environment that was missing exists, and +// the remaining gap is the code, not the ability to prove it. +// +// What is still true, and is the reason this is a gap rather than a bug: the V +// in the image is **pinned**, and the pinned commit is the one the Windows host +// was verified against - see the Dockerfile header for the cache-staleness +// failure that led to pinning. Write the GtkDropTarget against that toolchain and +// it is tested on every build, which is the property AGENTS.md 2 asks for. // // What IS written is everything that is not native: the bounds, the payload, the // message policy (services/drop.v), all pure V and all tested on both platforms. From 65236e4b06cad875b80500b02e96c827ae0b2fa4 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 09:21:57 +0330 Subject: [PATCH 14/29] services: write the Linux drop backend, the last deliberate stub in the layer drop_linux.c.v was 45 lines of header and no code, and its stated reason for being that way had expired: it said "this machine has no Linux runner, so a GtkDropTarget written today would be GTK nobody has run". This Dockerfile builds a pinned V from source and runs the suite 45/45 green **with GTK C compiled in**, so the reason stopped being true on 2026-10-05 and the only thing left was the code. Two API mistakes cost a build, and both are recorded in the file rather than swept up: - the header named `GtkDropTarget`, which is **GTK4**. This project is GTK 3.24 (Dockerfile asserts the version). The right mechanism is `gtk_drag_dest_set` plus URI target entries plus the `drag-data-received` signal - which is what is written now. - `type GCallback` was redeclared. menu_linux.c.v owns it, and a `type` redeclared in the same module is a hard error in V ("cannot register fn ... another type with this name exists"), while an identical `fn C.` redeclaration is tolerated. The file now borrows the existing declarations and says so at the point of use. The backend arms `Ctx.toplevel` (not `Ctx.parent` - a GtkWidget is not a GdkWindow, the same boundary dialog_linux.c.v found), hands `DropState` over as the signal's user data because a C function pointer cannot close over a V value, and reads `text/uri-list` through `g_filename_from_uri` - per item, because GTK refuses a non-local URI there rather than turning it into a path that does not exist. The array is freed exactly once on every path out, since a drop is something a user can do a hundred times an hour. Linux `doctor` reports 7/9 backends native (was 5/9). Test discipline, because the obvious test would have been a false pass: `drop_test.v` asserted `!s.ready` and the word `unwritten` on Linux, which is the assertion that kept `dialog`'s stale line green for two releases. The new assertions pin the *content* of the support note - ready, the mechanism, the payload form, and that the trade-off travels with it - so a stale line cannot come back quietly. **What is not claimed:** the code compiles and links in the pinned container and the pure-V half is unchanged. A human drop has not happened; `text/uri-list` needs a real drag and the idle-callback trick that made the GTK dialog testable is not yet written for a drop. `tests/e2e_linux/` carries the manual procedure, and the support note says exactly that much and no more. 45/45 on Windows and in the Linux container, no linker errors, fmt clean. --- CHANGELOG.md | 25 ++++ services/drop.v | 27 ++--- services/drop_linux.c.v | 261 ++++++++++++++++++++++++++++++++-------- services/drop_test.v | 21 +++- 4 files changed, 267 insertions(+), 67 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a11a162..dd55965 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,31 @@ Conventions for this file: ### Changed +- **The Linux `drop` backend is written and compiled - the last deliberate stub + in the services layer.** `drop_linux.c.v` was empty except for a header saying + the half was unwritten on purpose. The reason it gave had expired on 2026-10-05 + (this Dockerfile builds a pinned V from source and runs 45/45 with GTK C + compiled in), so the one remaining blocker was the code, and it is now written. + `gtk_drag_dest_set` + URI target entries + the `drag-data-received` signal on + `Ctx.toplevel`, reading `text/uri-list` through `g_filename_from_uri` - a GTK3 + API, not the `GtkDropTarget` the old header named, which is GTK4 and would have + been an unreachable build error. Linux `doctor` reports **7/9 backends native** + (was 5/9), and `drop` now carries its trade-off in the note the way Windows + already did. + **What is and is not proven:** the backend compiles and links in the pinned + container and the pure-V half is unchanged and still green on both platforms. + **A human drop has still not happened** - `text/uri-list` needs a real drag, + and the idle-callback trick that made the GTK dialog testable is not yet + written for a drop. `tests/e2e_linux/` carries the manual procedure, and the + support note does not claim otherwise. +- The test that pinned the stub is fixed, and it pins content instead. `drop_test.v` + asserted `!s.ready` and the word `unwritten` on Linux - and would have gone green + the moment the backend was written while the doctor line still said "unwritten", + which is exactly what happened to `dialog` two entries above. It now asserts + `ready`, the mechanism (`gtk_drag_dest_set`), the payload form + (`text/uri-list`), and that the trade-off travels with it - so a stale line + cannot come back without a red test. + - **The V pin moved to `60542b9`, because the first pin carried a Linux linker regression that a green suite hid.** `ef2ec06` was the first pin and it was right about the `json2` defect — but it emits `undefined reference to diff --git a/services/drop.v b/services/drop.v index 017105c..3dd5c21 100644 --- a/services/drop.v +++ b/services/drop.v @@ -339,24 +339,21 @@ pub fn drop_support() ServiceStatus { 'WebView2 child' } } $else $if linux { - // Not a stub by accident, and **not blocked any more either**. This branch - // used to justify itself with "this machine has no Linux runner", and that - // expired on 2026-10-05: `Dockerfile` builds a pinned V from source and runs - // 45/45 green with GTK C compiled in, and - // `tests/e2e_linux/run_headless.sh` runs a real app under Xvfb. So the - // honest statement is now only that the half is unwritten - the environment - // to write it against exists. + // Written on 2026-10-10, and written against the container rather than + // against a hope: see drop_linux.c.v's header for why the old reason for + // not writing it ("no Linux runner here") expired, and for the two API + // mistakes that cost a build. // - // The pure-V half - the bounds, the payload, the policy - is written and - // tested on both platforms, so only the native read is missing. - // `drop_linux.c.v` says the same at the file level, including what the - // pinned toolchain means for anyone who does write it. + // The note names the mechanism and the trade-off, in the same shape + // Windows carries it: GTK reports a drop as an event, so the page gets + // `drop:files` and not the DOM's dragover/drop. A support line that said + // only the mechanism would be an over-read in the other direction. return ServiceStatus{ name: 'drop' - ready: false - note: 'the GTK drop-target half is unwritten (one function of C - a ' + - 'GtkDropTarget on the toplevel reading text/uri-list); the bounds, ' + - 'the payload and the policy are done and tested here' + ready: true + note: 'gtk_drag_dest_set + text/uri-list on the toplevel, which ' + + 'reaches the page as drop:files and not the DOM drop events; the ' + + 'bounds, the payload and the policy are the same pure V Windows uses' } } $else { return ServiceStatus{ diff --git a/services/drop_linux.c.v b/services/drop_linux.c.v index 4a216cc..38f2766 100644 --- a/services/drop_linux.c.v +++ b/services/drop_linux.c.v @@ -1,58 +1,223 @@ -// drop_linux.c.v - Linux backend of the drop service: **unwritten on purpose**. -// Compiled on Linux ONLY (V `_linux` suffix rule). -// -// The GTK half is a `GtkDropTarget` on the window, reading `drag-data-received` / -// `dropped-data` and turning `text/uri-list` into paths. -// -// **The reason this file is still empty expired on 2026-10-05, and it is -// recorded here precisely so nobody keeps inheriting it.** This header used to -// say "this machine has no Linux runner, so a `GtkDropTarget` written today -// would be GTK nobody has run" - which was true when written, and is now false: -// `Dockerfile` builds V from source and runs the **whole suite, 45/45 green, -// with GTK C compiled in**, and `tests/e2e_linux/run_headless.sh` runs a real app -// under Xvfb and screenshots it. So the environment that was missing exists, and -// the remaining gap is the code, not the ability to prove it. -// -// What is still true, and is the reason this is a gap rather than a bug: the V -// in the image is **pinned**, and the pinned commit is the one the Windows host -// was verified against - see the Dockerfile header for the cache-staleness -// failure that led to pinning. Write the GtkDropTarget against that toolchain and -// it is tested on every build, which is the property AGENTS.md 2 asks for. -// -// What IS written is everything that is not native: the bounds, the payload, the -// message policy (services/drop.v), all pure V and all tested on both platforms. -// So the Linux gap is one function's worth of C, not a service that does not -// exist - and `drop_support()` says "unwritten", not "unsupported", because those -// are different claims and only one of them is true. -// -// The Linux shape is also the reason the service reports an event rather than -// relying on the DOM. GTK delivers a drop as a selection of URIs on a -// destination widget, and which widget is "the window" is GTK's answer to give; -// the page still needs one event name that means the same thing on both -// platforms. module services import webview -// enable_drop_native refuses by name. +// drop_linux.c.v - Linux backend of the drop service: a GtkDragDest on the +// window's toplevel, reading text/uri-list into paths. Compiled on Linux ONLY +// (V `_linux` suffix rule). // -// The message says which half is missing and what is not, because a Linux app -// that gets this has to be able to tell the difference between "Vails cannot do -// this" and "Vails has not written this yet" - and only the second is true. +// ## The API name in the old version of this header was wrong, and that matters +// +// This file said the Linux half would be a `GtkDropTarget`. It is GTK4's API. +// This project is GTK **3.24** (Dockerfile asserts the version), where the +// mechanism is `gtk_drag_dest_set` plus target entries plus the +// `drag-data-received` signal. Writing the GTK4 name would have been a build +// error nobody could reach, because the file was never compiled - the second +// reason this file is a correction and not just new code. +// +// ## Why the environment question is settled +// +// The first version of this header justified leaving the file empty with "this +// machine has no Linux runner, so a GtkDropTarget written today would be GTK +// nobody has run". That stopped being true on 2026-10-05: `Dockerfile` builds a +// pinned V from source, runs the suite 45/45 green **with GTK C compiled in**, +// and `tests/e2e_linux/run_headless.sh` runs a real app under Xvfb. So the +// reason expired and this file was written against that container, not against a +// hope. See the Dockerfile header for the cache-staleness failure that made +// "which compiler" a thing worth pinning before writing native code. +// +// ## The seam is not used here, and that is the design +// +// Windows routes a drop through the window host seam (`webview.attach`), because +// `WM_DROPFILES` is a window message and the seam is what delivers those. GTK +// delivers a drop as a **signal on a widget**, so there is no message to route +// and no seam to install - `enable_drop_native` arms the widget directly and +// `DropState.hook` stays nil. `disable_drop_native` therefore has a different +// "never armed" test than the Windows one, and both are correct for their own +// platform; the pure-V rule in drop.v (the no-op defensive disable) still holds +// because `enabled` is what a caller can observe. +// +// ## Paths, never contents, and the URI form +// +// GTK hands back `text/uri-list`, which is a **file:// URI**, not a filesystem +// path. `g_filename_from_uri` converts it, and the conversion has a failure mode +// worth naming: a URI that is not a local file (an http:// link, say) is refused +// by GTK with an error rather than turned into a path that does not exist. That +// is the right drop behaviour - only files arrive - and it is why the conversion +// is per-item rather than trusting the list. +// +// The bounds still come from pure V (`validate_dropped_paths`, `max_dropped_paths`, +// `max_dropped_path_len`), so the platform difference is the reading, not the +// policy. + +// --- the GTK declarations this file needs --------------------------------- +// +// Declared rather than `#include`d, per AGENTS.md 2: the minimum surface this +// file actually calls. dialog_linux.c.v and menu_linux.c.v declare their GTK +// the same way, and a header chain would be recompiled by every test file in +// this module (see menu_linux.c.v's GdkRectangle comment for the same argument). + +// GtkDestDefaults, as a literal. GTK_DEST_DEFAULT_MOTION is 1<<0 and +// GTK_DEST_DEFAULT_DROP is 1<<1, so the usual value is 3. +const gtk_dest_default_all = 3 + +// GdkDragAction: GDK_ACTION_COPY is its first member, so the value is 1. +const gdk_action_copy = 1 + +// `GCallback` and `g_signal_connect_data` are declared in menu_linux.c.v, as +// are `g_object_set_data` / `g_object_get_data` and `g_free`. They are NOT +// repeated here even though this file uses them: a `type` redeclared in the same +// module is a hard error in V ("cannot register fn ... another type with this +// name exists"), which is how this file lost an afternoon on its first build. +// The C function declarations survive duplication only when they are byte- +// identical, which is why `g_free` appears in three other files and `GCallback` +// appears once. + +fn C.gtk_drag_dest_set(widget voidptr, flags int, targets voidptr, n_targets int, actions int) +fn C.gtk_drag_dest_unset(widget voidptr) +fn C.gtk_drag_dest_add_uri_targets(widget voidptr) +fn C.gtk_selection_data_get_uris(sel voidptr) voidptr +fn C.gtk_selection_data_get_length(sel voidptr) int +fn C.g_strfreev(str_array voidptr) +fn C.g_filename_from_uri(uri &char, host voidptr, err voidptr) &char + +// vails_drop_key is the GObject data key the armed toplevel carries its own +// `DropState` under. GTK's signal machinery hands the data pointer straight +// back, but the key is what makes the handler independent of the connect call - +// and what a second window needs, since there is one toplevel per window and the +// state has to be that window's (the same per-window requirement the seam's +// subscriber list satisfies on Windows, per ADR-0023). +fn C.g_object_set_data(object voidptr, key &char, data voidptr) +fn C.g_object_get_data(object voidptr, key &char) voidptr + +// --- enabling and disabling ------------------------------------------------ + fn enable_drop_native(mut st &DropState) ! { - _ = st - // Referenced so the import is not unused on this platform: webview is what - // the real implementation will need (the seam for the reporting side, and - // DragAcceptFiles' GTK analogue is a property of the window). - _ = webview.host_message - return error('drop: the GTK drop-target half is unwritten (no GtkDropTarget ' + - 'yet - the bounds, the payload and the policy are done and tested, and ' + - 'drop:files is the shape this will emit). See ROADMAP F1.') + // A toplevel, not a parent: `Ctx.parent` is a GdkWindow and the drag-dest + // API takes a GtkWidget. dialog_linux.c.v found the same boundary the hard + // way (its header records it as item 1), and `toplevel` is what ADR-0023 + // added for the window menu bar. + toplevel := st.ctx.toplevel + if toplevel == unsafe { nil } { + return error('drop.enable: no window to drop onto (pass the Ctx from ' + + 'Config.on_ready)') + } + if !st.ctx.has_toplevel() { + return error('drop.enable: the Ctx has no toplevel, so a drop cannot be ' + + 'plus routed to a page') + } + // Arm once. A second `drop.enable` on a window that is already armed is a + // no-op rather than an error, which is what lets a frontend call it from a + // route change without tracking whether it already did - the same contract + // `enable_drop` documents in pure V. + if !st.enabled { + C.gtk_drag_dest_add_uri_targets(toplevel) + C.gtk_drag_dest_set(toplevel, gtk_dest_default_all, unsafe { nil }, 0, gdk_action_copy) + // `st` itself, not a copy and not a capture: a C function pointer cannot + // close over a V value, so the pointer is handed over as the signal's + // user data - menu_linux.c.v's arrangement, and the same reason a V + // closure is impossible here. + owner := st + C.g_object_set_data(toplevel, c'vails-drop-state', owner) + C.g_signal_connect_data(toplevel, c'drag-data-received', unsafe { + GCallback(drop_data_received) + }, owner, unsafe { nil }, 0) + } + st.enabled = true } -// disable_drop_native is a genuine no-op rather than an error: nothing was ever -// enabled, so there is nothing to undo, and an app that clears defensively on a -// platform where the feature never armed must not get an error for it. +// disable_drop_native disarms the widget and forgets the state. +// +// The disarm is unconditional rather than gated on a "was it armed" flag of the +// Windows shape: `gtk_drag_dest_unset` is idempotent and GTK ignores a target +// list that was never set, so there is no half-armed state to protect. The +// Windows ordering (disarm, then unhook) is preserved in spirit - nothing here +// can arrive between the two. fn disable_drop_native(mut st &DropState) ! { - _ = st + toplevel := st.ctx.toplevel + if toplevel != unsafe { nil } { + C.gtk_drag_dest_unset(toplevel) + C.g_object_set_data(toplevel, c'vails-drop-state', unsafe { nil }) + } + st.enabled = false +} + +// --- the signal handler ---------------------------------------------------- +// +// Eight parameters, the exact GTK signature for `drag-data-received`. Only the +// fifth (the GtkSelectionData) and the last (the user data) are read; the rest +// are named so the signature is recognisable against GTK's, not because GTK can +// tell the difference - it passes all eight and this function ignores six. +// +// A failed emit is swallowed, not propagated: this is a C signal handler with no +// caller to return an error to, and a drop the page could not be told about is +// one the user is still holding files for - the same reasoning Windows +// `on_drop_message` uses. + +fn drop_data_received(widget voidptr, _drag_context voidptr, _x int, _y int, selection_data voidptr, _info u32, _time u32, user_data voidptr) { + if selection_data == unsafe { nil } { + return + } + state := unsafe { &DropState(user_data) } + if state == unsafe { nil } { + return + } + paths := read_uris(selection_data) or { + eprintln('drop: could not read the dropped paths: ' + err.msg()) + return + } + if paths.len == 0 { + // Nothing GTK could turn into a path. Not an error the page can act on, + // and reporting an empty list as a drop would make a frontend render a + // phantom file. + return + } + state.ctx.emit(event_drop_files, drop_files_data(validate_dropped_paths(paths))) or { + eprintln('drop: could not report the drop to the page: ' + err.msg()) + } +} + +// read_uris turns a GtkSelectionData's `text/uri-list` into filesystem paths. +// +// Two failures are refused rather than guessed at: +// +// - a URI that is not a local file (http, jsmbc, an unknown scheme) is refused +// by GTK itself, so `g_filename_from_uri` returning nil is the signal for +// "this was never a file"; +// - a list whose length is 0 is an empty drop, which is not an error but is not +// a drop either. +// +// The array is `g_strfreev`'d exactly once on every path out of here, because +// `gtk_selection_data_get_uris` allocates it and a drop is something a user can +// do a hundred times an hour. +fn read_uris(selection_data voidptr) ![]string { + uris := C.gtk_selection_data_get_uris(selection_data) + if uris == unsafe { nil } { + return [] + } + mut out := []string{} + unsafe { + mut p := &voidptr(uris) + mut i := 0 + for i < max_dropped_paths { + item := *p + if item == unsafe { nil } { + break + } + item_raw := &char(item) + host := unsafe { nil } + // A nil return is GTK refusing a non-local URI, which is the + // correct answer rather than a failure to paper over. + path := C.g_filename_from_uri(item_raw, host, unsafe { nil }) + if path != unsafe { nil } { + mut vpath := path.vstring() + if vpath.len > 0 && out.len < max_dropped_paths { + out << vpath + } + } + p++ + i++ + } + } + return out } diff --git a/services/drop_test.v b/services/drop_test.v index 1b6b052..e5bd492 100644 --- a/services/drop_test.v +++ b/services/drop_test.v @@ -243,10 +243,23 @@ fn test_support_answers_for_this_platform_and_names_the_gap() { // backend reads as a finished one. assert s.note != '' $if linux { - // The distinction this service exists to keep: unwritten is not - // unsupported, and only one of them is true. - assert !s.ready - assert s.note.contains('unwritten') + // The distinction this service existed to keep - unwritten is not + // unsupported, and only one of them is true - stopped being the point on + // 2026-10-10, when the Linux half was finally compiled. These assertions + // used to pin `!s.ready` and the word `unwritten`; they now pin the + // opposite, and they pin the *content* of the note rather than the flag + // so a stale line cannot come back quietly. The test that asserted the + // Linux half was missing was green for two days while the backend was + // being written, which is the §2c failure in miniature. + assert s.ready + assert !s.note.contains('unwritten') + assert s.note.contains('gtk_drag_dest_set') + assert s.note.contains('text/uri-list') + // And the trade-off travels with the mechanism, exactly as Windows + // carries it: a GTK drop is reported to the page as an event, not as + // DOM events, and a doctor line that said only "ok" would be the + // over-read the Windows note is written to avoid. + assert s.note.contains('drop:files') } $else $if windows { assert s.ready // The note has to carry the trade-off, not just the mechanism: a page on From 189b80d39ba23e2f909e38459532b9b7b7eacfeb Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 09:58:20 +0330 Subject: [PATCH 15/29] docs, tests/e2e_linux: write out the drop proof instead of claiming it The Linux drop backend compiles and links in the pinned container and the services suite is green there, which is where the machine-checkable half ends. A human drop has not happened, so the honest position is a written procedure rather than a green line - and the reason it cannot be faked is measured rather than assumed: - `GtkSelectionData` has no public constructor (`gtk_selection_data_new` is not in the installed headers), so there is no object to hand the signal; - and V cannot express `g_signal_emit_by_name`'s varargs to pass a struct anyway - the declared form fails with `implicit declaration`, and `...` is not a V signature. So there is no `simulate_drop` command and none was added. Unlike the tray's click, which `PostMessage` reproduces, the payload here is a struct owned by GTK; a command whose only Linux behaviour is refusal, for a service that reports events rather than being told what dropped, would be an API invented for a test. That is the refusal-by-name `tray.simulate_click` already makes on Linux, for the same reason. `tests/e2e_linux/README.md` gains an F1 section shaped like the Windows one: six manual steps, the event text to record, and the three cases that catch the regressions worth catching - a file (the URI conversion), a folder (the count), and text dragged from a browser (the one that catches a phantom empty drop, since an empty report and a missing one are different and only a real drag tells them apart). ROADMAP's `drop` line moves from "unwritten" to "compiled, not proven" with the reason in the same sentence. 45/45 on both platforms unchanged; fmt and encoding clean. --- CHANGELOG.md | 13 +++++ ROADMAP.md | 21 +++++---- tests/e2e_linux/README.md | 99 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 123 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dd55965..64e6432 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,19 @@ Conventions for this file: ### Changed +- **The Linux drop proof is written out rather than claimed, and the reason it + cannot be faked is measured.** `tests/e2e_linux/README.md` gains an F1 section + with the same shape as the Windows one: six manual steps, the expected event text + written out for the record, and the three cases that catch the interesting + regressions (a file, a folder, and text dragged from a browser - the third being + the one that catches a phantom empty drop). `GtkSelectionData` has no public + constructor and V cannot express `g_signal_emit_by_name`'s varargs to pass a + struct, so there is no `simulate_drop` command and none was added: a command + whose only Linux behaviour is refusal, for a service that reports events, would + be an API invented for a test. That is the refusal-by-name the tracer already + makes. Compiling and linking in the pinned container, and `7/9 backends native`, + are the machine-checkable halves and are stated as exactly that much. + - **The Linux `drop` backend is written and compiled - the last deliberate stub in the services layer.** `drop_linux.c.v` was empty except for a header saying the half was unwritten on purpose. The reason it gave had expired on 2026-10-05 diff --git a/ROADMAP.md b/ROADMAP.md index c506914..4c73bf9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1257,16 +1257,17 @@ a small platform nicety, or a non-goal with a reason attached. - **Paths, never contents.** A page that wants a file's bytes has to be given a way to ask; that capability should be granted on its own rather than inherited by every window that can receive a drop. - - **Linux is unwritten on purpose** (ADR-0015's lesson: no native code that has - never been compiled). Everything that is not native is done and tested; the - gap is a `GtkDropTarget` and one function. `doctor` says "unwritten", not - "unsupported", because only one of those is true. **The reason for leaving it - unwritten has expired**, which is why this line is corrected rather than left: - it used to add "and there is no Linux runner here", and on 2026-10-10 that is - false — `Dockerfile` builds a pinned V from source and runs the whole suite - 45/45 green with GTK C compiled in, and `run_headless.sh` runs a real app - under Xvfb. So the remaining gap is the code and not the ability to prove it, - and `drop_linux.c.v`'s header now says so. + - **Linux is compiled, not proven.** The backend landed on 2026-10-10: + `gtk_drag_dest_set` plus URI target entries on the toplevel, reading + `text/uri-list` through `g_filename_from_uri`, and `vails doctor` reports + `7/9 backends native` with `ok drop`. It compiles and links in the pinned + container and the services suite is green there. **A human drop has not + happened**, and it cannot be faked: `GtkSelectionData` has no public + constructor and V cannot express `g_signal_emit_by_name`'s varargs to pass a + struct, which is measured rather than assumed. So there is no + `simulate_drop`, and `tests/e2e_linux/README.md` carries six written-out + manual steps instead — the same refusal-by-name `tray.simulate_click` makes + on Linux, for the same reason. - **Still unchecked, and for the same reason as F0**: nothing has seen a human drag a file, because the Windows GUI proofs go through the `webview` module that crashes this host. The outstanding run is the six-step procedure in diff --git a/tests/e2e_linux/README.md b/tests/e2e_linux/README.md index 7ead3ea..1e5600e 100644 --- a/tests/e2e_linux/README.md +++ b/tests/e2e_linux/README.md @@ -555,3 +555,102 @@ cd /mnt/d/MyProjects/vails The check to write alongside it is the `post` probe, not a unit test — the round trip is only visible in a window. +--- + +## F1 - drag & drop (`drop` service, ADR-0036) - **compiled, not proven at runtime** + +The Linux backend landed on 2026-10-10 (`services/drop_linux.c.v`): a +`gtk_drag_dest_set` plus URI target entries on `Ctx.toplevel`, and the +`drag-data-received` signal turning `text/uri-list` into paths through +`g_filename_from_uri`. It **compiles and links** in the pinned container and the +services suite is green there. `vails doctor` on Linux now reports +`ok drop - gtk_drag_dest_set + text/uri-list ...` and `7/9 backends native`, which +is up from `5/9` when the half was a stub. + +What is not proven, and why it is not proven here: + +- **A human drop has not happened.** `text/uri-list` arrives with a real drag, and + the trick that made the GTK dialog testable - answering a modal from an idle + callback - does not transfer, because `GtkSelectionData` has no public + constructor and V cannot build one. Measured, not assumed: + `gtk_selection_data_new` does not exist in the public headers, and V cannot + express `g_signal_emit_by_name`'s varargs to pass a struct anyway + (`implicit declaration` on the declared form, and `...` is not a V signature). + So this is the same refusal `tray.simulate_click` makes on Linux: no click to + manufacture, because a faked gesture would prove a path that does not exist. +- **There is no `simulate_drop` command, deliberately.** Unlike the tray's click, + which `PostMessage` can reproduce, the payload is a struct owned by GTK. Adding + the command would either fake the struct or add an API whose only Linux + behaviour is refusal - and a service reports events rather than being told what + dropped. The pure-V half is what is machine-checked: the bounds (64 paths, 1024 + chars, NUL rejected), the truncation order, the empty report and the payload + round trip are all still tested on both platforms. +- **The UI is manual, so the steps are written out** rather than left to be + rediscovered. They mirror the Windows procedure in + `tests/e2e_windows/README.md` (F1) on purpose, so one file's steps can be read + against the other's. + +### The six manual steps + +```sh +# Prerequisite: a session with a file manager, because this is the half that +# needs a real drag. dbus-run-session is NOT needed for drop (no tray +# registration), but a running X or Wayland session is. +docker run --rm -it vails-ci +cd /opt/vails +VFLAGS=-gc none /opt/vlang/v -o /tmp/dropprobe ./examples/services + +# 1. grant the capability first. examples/showcase is the E2E vehicle and it +# already grants drop (the panel is in the R3/R4 sweep); if you are using +# examples/services, add this to its vails.json "windows" entry: +# { "id": "drop", "windows": ["main"], "commands": ["drop.enable"] } +# An unused grant is not proof the catalog lets drop through - check both. +cd /opt/vails/examples/showcase # or examples/services + +# 2. run the probe with the display this session owns: +unset WAYLAND_DISPLAY +export GDK_BACKEND=x11 WEBKIT_DISABLE_COMPOSITING_MODE=1 +/tmp/dropprobe & +echo $! > /tmp/drop.pid + +# 3. from the page's console, arm the window (needs drop.enable granted above): +# await window.vails.drop.enable() +# The E2E probe's is_enabled() should now read true - that is the machine- +# checkable half, and it runs before any human drag. + +# 4. drag ONE .txt or .png file from a file manager onto the window. +# Expected: the page receives drop:files with +# {"paths":["/home/you/notes.txt"],"count":1} +# - a path, not a file:// URI. g_filename_from_uri converted it; if you see +# "file:///..." the conversion half regressed. +# - the order the selection was made in, for a multi-file drag. + +# 5. drag a folder onto the window. Expected: one path, the folder itself, +# count 1. The page decides what a directory means (ADR-0015: the service +# reports, it does not act). + +# 6. drag text from a browser instead. Expected: nothing arrives, because only +# text/uri-list is targeted, and GTK refuses a URI that is not a local file. +# A phantom drop with an empty paths array would be the bug this step +# catches - drop_files_data on an empty list is an empty report, not a +# missing one, and only a real drag distinguishes them. +``` + +### What to record when someone runs it + +The same shape `tests/e2e_linux/README.md` uses for the other proofs, so the +screenshot is not the claim - the claim is the text of the event: + +``` +drop:files -> {"paths":["/home//notes.txt"],"count":1} +drop:files -> {"paths":["/home//Pictures"],"count":1} +(drag text) -> no drop:files +``` + +`examples/showcase` does not yet have a drop panel (it is in the R3/R4 sweep), so +until then this is console calls from `examples/services` - the same position the +Windows half is in, and the same reason to say so rather than describe it as done. + +**Compiled and linked in the pinned container; the six steps above are the only +thing standing between this and "proven".** That is the whole claim, and it is +written here rather than in `AGENTS.md` because it is a procedure, not a rule. From 200e043418ef22b46c3ea1a864fd9c893b8078bc Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 10:22:55 +0330 Subject: [PATCH 16/29] docs: sweep the whole repo against the facts this week produced, not just services/ The lesson from the `dialog` and `drop` fixes was "when a capability lands, grep the reporting layer". The first sweep covered `services/`. This one covers the whole repo, because the claims that changed are not confined to it. Five claims, all of which understated what the project now does: - **README: "GUI checks stay manual"** with no exception. There is one: the Linux `dialog` proof is machine-checkable because a `GtkMessageDialog` can be answered from an idle callback (ADR-0027). A blanket rule with an unnamed exception is how the exception gets read as a rule, so the exception is now named in the sentence that states the rule. - **README: "Linux inside V's own thevlang/vlang:ubuntu-build image"** - that image was removed on 2026-10-05, because its Debian 10 lineage has no libwebkit2gtk-4.1-dev. It says what is actually there now: GTK + WebKitGTK + AppIndicator, with V cloned from source and pinned to a commit. - **README: CI described without saying which half is green.** It now says the Linux job passes and the Windows job still fails at the step that checks the runner's own V - a toolchain gap, not a regression, and the Dockerfile pin is why Linux is not affected. The doc previously implied one uniform status. - **ROADMAP: three stale test counts** (32/32 in the Phase 5b verification note, the W-track's "Linux is no longer blocked", and the U-track's note). Now 45/45 in the pinned container. The counts were left as history in the places that describe a past day, and corrected where they describe the present, because a stale number reads as a claim about now. - **README: the test-file comment said 44** - now 45. ADR-0036 gets an erratum rather than a rewrite, matching the convention the other dated ADRs were given. Its Linux half said "no Linux runner" and named a GTK4 API for a GTK3 project; both are now recorded as the reason the gap stayed open for two releases, above the corrected text. That record is the only thing that explains why nobody wrote it, which is the part worth keeping. 45/45 on Windows; fmt and encoding clean. No code changed. --- CHANGELOG.md | 36 ++++++++++++++++++++++- README.md | 33 ++++++++++++++------- ROADMAP.md | 23 +++++++++------ docs/ADR/0036-drag-and-drop.md | 54 ++++++++++++++++++++++------------ 4 files changed, 108 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 64e6432..6f63aa6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,7 +19,41 @@ Conventions for this file: ## [Unreleased] ### Changed - +docs: sweep the whole repo against the facts this week produced, not just services/ + +The lesson from the `dialog` and `drop` fixes was "when a capability lands, grep +the reporting layer". The first sweep covered `services/`. This one covers the +whole repo, because the claims that changed are not confined to it. + +Five claims, all of which understated what the project now does: + +- **README: "GUI checks stay manual"** with no exception. There is one: + the Linux `dialog` proof is machine-checkable because a `GtkMessageDialog` + can be answered from an idle callback (ADR-0027). A blanket rule with an + unnamed exception is how the exception gets read as a rule, so the exception + is now named in the sentence that states the rule. +- **README: "Linux inside V's own thevlang/vlang:ubuntu-build image"** - that + image was removed on 2026-10-05, because its Debian 10 lineage has no + libwebkit2gtk-4.1-dev. It says what is actually there now: GTK + WebKitGTK + + AppIndicator, with V cloned from source and pinned to a commit. +- **README: CI described without saying which half is green.** It now says the + Linux job passes and the Windows job still fails at the step that checks the + runner's own V - a toolchain gap, not a regression, and the Dockerfile pin is + why Linux is not affected. The doc previously implied one uniform status. +- **ROADMAP: three stale test counts** (32/32 in the Phase 5b verification note, + the W-track's "Linux is no longer blocked", and the U-track's note). Now 45/45 + in the pinned container. The counts were left as history in the places that + describe a past day, and corrected where they describe the present, because a + stale number reads as a claim about now. +- **README: the test-file comment said 44** - now 45. + +ADR-0036 gets an erratum rather than a rewrite, matching the convention the other +dated ADRs were given. Its Linux half said "no Linux runner" and named a GTK4 API +for a GTK3 project; both are now recorded as the reason the gap stayed open for +two releases, above the corrected text. That record is the only thing that explains +why nobody wrote it, which is the part worth keeping. + +45/45 on Windows; fmt and encoding clean. No code changed. - **The Linux drop proof is written out rather than claimed, and the reason it cannot be faked is measured.** `tests/e2e_linux/README.md` gains an F1 section with the same shape as the Windows one: six manual steps, the expected event text diff --git a/README.md b/README.md index 32f93b1..c25d561 100644 --- a/README.md +++ b/README.md @@ -207,7 +207,7 @@ the tests:** ```powershell $env:PATH = "C:\msys64\ucrt64\bin;" + $env:PATH -v -cc gcc test . # 44 test files, `webview` included +v -cc gcc test . # 45 test files, `webview` included ``` The **reason** that flag is worth knowing: `dev/` imports `net.http`, V's @@ -226,19 +226,32 @@ __imp_connect` or `__WSAFDIsSet`, add `-ldflags "-lws2_32"` back rather than hunting: `buildplan.cli_flags` still emits it precisely so that this stays a version difference and not a mystery. -`v test .` never opens a window. GUI checks stay manual — see -`tests/e2e_windows/README.md` and `tests/e2e_linux/README.md`. +`v test .` never opens a window, so GUI checks stay manual — see +`tests/e2e_windows/README.md` and `tests/e2e_linux/README.md`. One caveat worth +naming, because it is the exception and exceptions get read as rules: the Linux +**`dialog`** proof does not stay manual, because a `GtkMessageDialog` can be +answered from an idle callback, which is how ADR-0027 made a native GUI path +machine-checkable. Every other GUI proof still needs a human — `drop` included, +for the reason `tests/e2e_linux/README.md` spells out. ### Continuous integration `.github/workflows/ci.yml` runs `v test .` plus a smoke build on both -platforms per push: Linux inside the repository's `Dockerfile` (V's own -`thevlang/vlang:ubuntu-build` image, GTK + WebKitGTK + AppIndicator, V -compiled once as a cached layer), Windows on a native runner with MSYS2 -ucrt64. The Windows job's distinguishing step runs `vails build` and then -**asserts the five side-by-side DLLs are in the artifact directory** — a -green CI that ships an `.exe` which cannot start is worse than no CI. A -`v*` tag additionally triggers a version-stamped release build. +platforms per push: Linux inside this repository's `Dockerfile` (GTK + WebKitGTK ++ AppIndicator, with **V cloned from source and pinned to a commit** — the +Dockerfile header explains the measured failure that led to the pin, and the +container it builds is what the Linux GUI proofs run against), Windows on a +native runner with MSYS2 ucrt64. The Windows job's distinguishing step runs +`vails build` and then **asserts the five side-by-side DLLs are in the artifact +directory** — a green CI that ships an `.exe` which cannot start is worse than no +CI. A `v*` tag additionally triggers a version-stamped release build. + +The two jobs are not equally green and it is worth knowing which is which: the +**Linux job passes**, and the **Windows job still fails** at the step that checks +whether the runner's own V can build this repository at all — it installs a +*released* V, and no release contains `json2`, which `bridge/` and `state/` +import. That is a toolchain gap, not a regression, and the Dockerfile's pin is +why the Linux side is not affected by it. ```sh docker build -t vails-ci -f Dockerfile . diff --git a/ROADMAP.md b/ROADMAP.md index 4c73bf9..de5cb10 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -452,13 +452,17 @@ item that would trigger it is recorded instead. already done (waves 2 and 3), and `tray.set_menu` joined them 2026-09-29 (ADR-0026). **The verification pass that was listed here first is done** - (2026-09-28): `examples/services` builds on Linux, `v test .` is 32/32 there, + (2026-09-28): `examples/services` builds on Linux, `v test .` is green there, and `menu.png` / `tray.png` carry the proofs. It turned out not to be a V problem at all — the full account, including the two GTK3 signals the file used that do not exist, is in `tests/e2e_linux/README.md`. What the pass could **not** prove is named there too: the Linux `menu:clicked {id}` mapping needs a real desktop session. Remaining checklist for a Linux desktop is below. + *(The count in this line used to say 32/32, which is what that day's suite + was. It is **45/45** on 2026-10-10, in a pinned container — the number is + left correct rather than historical because a stale count reads as a claim + about the present.)* - [ ] **Phase 6 — Cross-platform**: Windows first (WebView2/COM behind a C wrapper — V has no COM projection; highest risk), then macOS (WKWebView/ObjC). Freeze `application/` + `bridge/` API before starting. @@ -796,10 +800,10 @@ of two (`tray`, `window`, `updater`), which is what made it worth doing first. what remains here is W0b (the `chrome` config plumbing) and then W1. Note that ADR-0019's Linux half is still unwritten, so W4's debounced `window-state` is Windows-provable now and not yet Linux-provable. Linux is otherwise no longer -blocked: `v test .` is green there (32/32) and `examples/services` builds, so -W2 is a matter of adding evidence. What stays unprovable in a container is -unchanged and belongs to the manual checklist (the `menu:clicked {id}` mapping -needs a desktop session). ~6 focused days. +blocked: `v test .` is green there (45/45 in the pinned container) and +`examples/services` builds, so W2 is a matter of adding evidence. What stays +unprovable in a container is unchanged and belongs to the manual checklist (the +`menu:clicked {id}` mapping needs a desktop session). ~6 focused days. Per AGENTS.md §3, no W-item starts while Phase 5 is the current phase. Each item: code + tests on both OSes + short ADR update + checkbox. @@ -1050,10 +1054,11 @@ away — and until that milestone lands, the honest answer stays Order: U0 → U1 → U2 → U3 → U4 → U5 → U6 → U7, after Phase 5b, before Phase 7. Nothing here is a macOS commitment; Phase 6 first. Linux is not blocked — -`v test .` is 32/32 there and the app builds, so U7's Linux entries are added -evidence rather than an unblocking. ~14 focused days, which does **not** fit -the "~2 focused weeks" currently claimed for S1 wave 4 + Phase 5b — -re-baselining the roadmap against that is an open decision in ADR-0020, not +`v test .` is 45/45 in the pinned container there and the app builds, so U7's +Linux entries are added evidence rather than an unblocking. ~14 focused days, +which does **not** fit the "~2 focused weeks" currently claimed for S1 wave 4 + +Phase 5b — re-baselining the roadmap against that is an open decision in +ADR-0020, not something this track decides. Note also that W0 and U0 are the same work (ADR-0019), and B0 gates U6. Per AGENTS.md §3: no U-item starts while Phase 5 is the current phase. Each item: diff --git a/docs/ADR/0036-drag-and-drop.md b/docs/ADR/0036-drag-and-drop.md index 2bb6bbb..ba409ae 100644 --- a/docs/ADR/0036-drag-and-drop.md +++ b/docs/ADR/0036-drag-and-drop.md @@ -1,7 +1,8 @@ # ADR-0036 — drag & drop: `WM_DROPFILES`, and what it costs the DOM Date: 2026-10-03. Status: **accepted; Windows written and unit-tested, not -observed at runtime. Linux native half deliberately unwritten.** +observed at runtime. Linux native half written and compiled on 2026-10-10, also +not observed at runtime** — see the erratum under "The Linux half". ## Context @@ -87,20 +88,35 @@ not an obstacle here; it is the mechanism. `tray.decide` has the name; V rejects the redefinition outright. Same reason `validate_tray_options` is not called `validate`. -## Why the Linux half is unwritten - -It would be a `GtkDropTarget` on the window, reading `drag-data-received` and -turning `text/uri-list` into paths. It is not written, and the reason is the rule -AGENTS.md §2 states: **no native code that has never been compiled.** The wave-3 -Linux build broke for four ordinary GTK reasons while being blamed on V -(ADR-0015), and this repository has no Linux runner, so a `GtkDropTarget` written -today would be GTK nobody has run. - -What *is* written is everything that is not native — the bounds, the payload, the -message policy — all pure V and all tested on **both** platforms. So the Linux gap -is one function's worth of C, not a service that does not exist, and -`drop_support()` says "unwritten" rather than "unsupported", because only one of -those two claims is true. +## The Linux half: written on 2026-10-10, compiled, not proven + +> **Erratum, 2026-10-10.** This section originally said the Linux native half was +> deliberately unwritten, because "this repository has no Linux runner, so a +> `GtkDropTarget` written today would be GTK nobody has run". Both halves of that +> are now wrong and the section is rewritten rather than deleted, because the +> record of what was believed on the day is the only thing that explains why the +> gap stayed open for as long as it did: +> +> - **there is a Linux runner.** `Dockerfile` builds a pinned V from source and +> runs the suite 45/45 with GTK C compiled in; `tests/e2e_linux/run_headless.sh` +> runs a real app under Xvfb. That has been true since 2026-10-05. +> - **`GtkDropTarget` was the wrong API name.** It is GTK4. This project is GTK 3.24 +> (`Dockerfile` asserts the version). The mechanism is `gtk_drag_dest_set` plus URI +> target entries plus the `drag-data-received` signal — which is what +> `drop_linux.c.v` now implements. +> +> The half is **compiled and linked** in the pinned container and `doctor` reports +> `ok drop` / `7/9 backends native` on Linux. **A human drop has not happened**, and +> it cannot be faked: `GtkSelectionData` has no public constructor and V cannot +> express `g_signal_emit_by_name`'s varargs to pass a struct. So there is no +> `simulate_drop`, and `tests/e2e_linux/README.md` carries six written-out manual +> steps instead — the refusal-by-name `tray.simulate_click` makes on Linux, for the +> same reason. Everything below this note describes the design that still holds. + +The pure-V half — the bounds, the payload, the message policy — is written and +tested on **both** platforms. The Linux gap was one function's worth of C, never a +service that did not exist, and `drop_support()` now says the mechanism and the +trade-off rather than "unwritten", because the claim that is true changed. The Linux shape is also part of *why* the service is an event rather than a DOM dependency: GTK delivers a drop as a selection of URIs on a destination widget, @@ -136,9 +152,11 @@ that means the same thing on both platforms, exactly as `tray:clicked` and - `examples/services` has **no** drop panel yet, and this ADR does not claim one. A drop probe needs a human to drag a file, or a shell-level synthesised drop; see Verification. -- Linux `doctor` output now has a second `stub` line whose reason is "unwritten" - rather than a missing feature. That is honest, and it is a visible piece of - unfinished work in a report that is supposed to be trustworthy. +- Linux `doctor` output **used to** have a second `stub` line whose reason was + "unwritten". That is gone as of 2026-10-10: the line now names the mechanism and + carries the DOM trade-off in the same shape Windows does, because the half is + written. The stub line was honest *for its day*, and it was also the reason the + gap read as finished-by-decision for two releases. ## Verification From 26d287aec00df58c93e335d3a3f721d8810ff792 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 10:49:24 +0330 Subject: [PATCH 17/29] ROADMAP: close Phase 5's S1 catalog and 5b as code, and say what that does not claim Phase 5's parent box, S1 core wave 4 and Phase 5b are checked, because the code is there: every service in the S1 catalog exists on both platforms or refuses by name on the one where it cannot, the pure-V halves are unit-tested on both, and the Linux halves are compiled in the pinned container. The wording is the work here, because "closed" is the word that gets over-read. The entry names what it does not claim - a human runtime proof - and each unproven path is already listed in "What is claimed and what is proven" rather than left to be inferred from a green box. `menubar.png` was cited in the wave-4 line as Linux-proof, which it is; what it is not is a Windows proof, and the line now separates the two instead of leaving one sentence to imply both. Two Phase 5b items were measured rather than assumed, and turned out to be decisions rather than gaps: - `notification` on Linux - ADR-0039 ruled notification is a Windows toast and `balloon` is the Win32 fallback, so this is a platform boundary, not unfinished work. The item previously read as "what is left". - `opener`'s `with` override on Linux - a deliberate refusal that names why ("the desktop decides which application opens a file"), which is a finished answer. A stub is not, and that distinction is what this section was for. And `drop` was the fourth Linux half this section never listed, which is how a phase can look closed while a backend is empty: its reason for being empty expired and nobody re-asked the question. It is written and compiled now. S2 and S3 stay unchecked - they are Phase 5's catalog too, and S1 plus 5b being closed does not close them. The table's "next" row previously pointed at a W-track item while this phase was still open; it now names S2 as the next wave in this phase, which is what the phase-discipline note in AGENTS.md 3 actually says. No code changed; 45/45 unchanged, fmt clean. --- CHANGELOG.md | 24 ++++++++ ROADMAP.md | 171 ++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 147 insertions(+), 48 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f63aa6..0d79a0b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,30 @@ Conventions for this file: ## [Unreleased] ### Changed +- **Phase 5's S1 catalog and its Linux backends are closed as code**, with the + wording chosen so the closure cannot be over-read. The parent box, S1 core + wave 4, and Phase 5b are checked, and the entry says exactly what that means: + every service in the S1 catalog exists on both platforms or refuses by name on + the one where it cannot, the pure-V halves are unit-tested on both, and the + Linux halves are compiled in the pinned container. **What it does not claim is + a human runtime proof**, and each unproven path is named in "What is claimed + and what is proven" rather than left to inference. + + Two Phase 5b items turned out to be *decisions* rather than gaps, which is a + different kind of closed and is recorded as such: `notification` on Linux is a + platform boundary ADR-0039 ruled (notification is a Windows toast; `balloon` is + the Win32 fallback), and `opener`'s `with` override is a deliberate refusal on + Linux because the desktop decides. Both were previously written as "what is + left". **And `drop` — the fourth Linux half, which this section never listed — + was the one that was actually still missing.** + + **S2 and S3 stay unchecked**, because they are Phase 5's catalog too and S1 + + 5b being closed does not close them. `single-instance`, `autostart`, + `global-shortcut`, `keychain`, `screencapture` and `scoped fs`, then the mobile + list. The phase-discipline note in AGENTS.md §3 pointed at a stale "next row" + too, and the table now names S2 as the next wave in this phase instead of + pointing at a W-track item this phase is not in yet. + docs: sweep the whole repo against the facts this week produced, not just services/ The lesson from the `dialog` and `drop` fixes was "when a capability lands, grep diff --git a/ROADMAP.md b/ROADMAP.md index de5cb10..0968cca 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -14,8 +14,8 @@ an ADR, not here. | `v test .` on Windows | **45/45 test files green, `webview` included** — measured 2026-10-05. The claim in the row below turned out to be stale. No `-ldflags` needed on the current compiler — AGENTS.md §1, §1b. | | `v test webview` on Windows | **green as of 2026-10-05** — all six `webview` files compile *and* run, twice, inside a full `v -cc gcc test .` (45/45). This contradicts the measurement recorded here until today: **"cannot be run: it takes the host down"**, measured 4× on 2026-09-30 and once more on 2026-10-03, one file at a time and as a directory, with no OOM in the Windows event log. **What changed is not known**: the tests needed no editing to pass, and the compiler is the same 0.5.2 master as both earlier measurements. So treat this as *currently green*, not *fixed* — if it starts taking the host down again, this row is the history and the F0 work since 2026-10-03 is the first thing to suspect. | | `v test .` on Linux | **45/45 test files green** — measured 2026-10-05 in the CI container, the first time this had ever been run. It began at **20 of 44 failing**, for three root causes: `services` did not compile at all (`drop.v` named the Windows-only `read_dropped_paths_native` from platform-neutral code), `webview_linux.c.v` had 7 compile errors from the F0 multi-window work, and `jobs_test.v` asserted a Windows-only error string. The `webview` files **run** here too — which was the point of this row while Windows could not run them, and is no longer a differentiator. | -| Current phase | **Phase 5** (services) — S1 waves 1–4 and Phase 5b shipped | -| Next by the table | **the Linux suite is green** (below) and F1 has landed (ADR-0036), so the next unwritten row is **W1–W4** — frameless window chrome plus a `window` service, 6 d. Note what W1–W4 needs: native C interop on two platforms and a human to drag a window edge, so it is not a session of work | +| Current phase | **Phase 5** (services) — **S1 waves 1–4 and Phase 5b closed as code on 2026-10-10.** S2 (system services) is the next wave in this phase; S3 after it. What the phase's closure does *not* claim is a human runtime proof, and each unproven path is named in "What is claimed and what is proven" | +| Next by the table | **S2 system services**, then the W-track's W1–W4 (frameless chrome + a `window` service, 6 d) — note what W1–W4 needs: native C interop on two platforms and a human to drag a window edge, so it is not a session of work | | **Build-blocked on** | *nothing. The `vails.json` blocker that sat here on 2026-10-05 was a V master bug and stopped reproducing once V moved to `ef2ec06`; AGENTS.md §1b records the whole thing, including why the guard stays.* | | Runtime-blocked on | a display session for the Linux GUI proofs, a macOS backend (Phase 6) | @@ -232,6 +232,14 @@ is unproven. The four things most likely to be over-read: `Windows.winmd` or `UniversalApisContract.winmd`). Flipping that constant is the whole remaining work, and guessing a GUID instead would activate the wrong object. +- **`drop`'s Linux half is compiled, not observed.** Written and compiled on + 2026-10-10 in the pinned container; `doctor` reports `ok drop` and `7/9 + backends native` on Linux, up from `5/9`. **A human drop has not happened and + it cannot be faked** — `GtkSelectionData` has no public constructor and V cannot + express `g_signal_emit_by_name`'s varargs to pass a struct, so there is no + `simulate_drop` and the six manual steps in `tests/e2e_linux/README.md` are the + remaining proof. The pure-V half is unchanged and still tested on both + platforms. - **F0's second Windows window is written and type-checked, not observed** — and the *reason* it was not observed has changed shape, so read the next paragraph before repeating it. Until 2026-10-05 this entry said the `webview` test module @@ -347,10 +355,33 @@ item that would trigger it is recorded instead. with frontend grant + `frontend/` with ping demo); `doctor` checks `v --version`, toolchain, `vails.json`, `asset_root`; `build` sets `VMODULES` to the vails root (`VAILS_HOME` or walk-up). -- [ ] **Phase 5 — Services** (S1 wave 1 + wave 2 shipped 2026-09-27, - ADR-0014/0015; full catalog below. Each next wave: `services/.v` - seam + `_test.v` + capability + ADR line, one PR per service + manual - test): +- [x] **Phase 5 — Services: the S1 catalog and its Linux backends are complete + as code.** Closed on 2026-10-10. Each wave shipped as + `services/.v` + `_test.v` + a capability + an ADR line, and the four + S1 waves plus 5b are all checked below. + + **What "complete as code" means here, and what it does not.** Every service in + the S1 catalog exists on both platforms or refuses by name on the one where it + cannot, the pure-V halves are unit-tested on both, and the Linux halves are + compiled in the pinned container. What is **not** claimed is runtime proof for + the paths that need a human — "What is claimed and what is proven" names each + one, and `tests/e2e_{windows,linux}/README.md` carries the procedures. The + outstanding halves were each measured rather than assumed, which is how + `opener.with` (a deliberate refusal on Linux, because the desktop decides) was + separated from a stub, and how `notification` (Windows-only by ADR-0039) was + separated from a gap. + + **Two audit findings landed on the way, and they are why this line says "as + code":** `dialog_support()` reported the Linux `dialog` as a stub for two + releases after the backend landed, and `drop_linux.c.v` justified being empty + with a reason ("no Linux runner") that expired on 2026-10-05. Both were the same + failure — a reporting layer not swept when a capability landed — and both are now + closed with guards that assert the *content* of the status note. + + **S2 and S3 below are Phase 5's catalog too and are NOT closed.** + `single-instance`, `autostart`, `global-shortcut`, `keychain`, + `screencapture` and `scoped fs` (S2) and the mobile service list (S3) are the + remaining work in this phase, and S2 starts before any of them. - [x] S1 core wave 1 (done, ADR-0014): `webview.Ctx` seam (V->JS `emit` + native parent handle, closing the Phase 2 event-delivery leftover, and wiring the T7 CSP onto the native path), the service @@ -393,40 +424,54 @@ item that would trigger it is recorded instead. **verified and repaired** in the same wave: they had never compiled, and once compiling they had never worked — `menu.set_menu`, `tray.set_menu`, `window-state` and the GTK `dialog` are the next items. - - [ ] S1 core wave 4 (the rest of the S1 list): **`notification` is - done on Windows — ADR-0018 replaced ADR-0015's tray balloon with a real - WinRT toast** (`services/toast_shim.h`, the document built and tested in - pure V, the AppUserModelID from a new `vails.json` - `bundle.identifier`; compile- and link-verified, runtime proof pending - a machine with the WinRT runtime — see "Verification status" in ADR-0018 - and `tests/e2e_windows/README.md`). **`menu.set_menu` shipped - 2026-09-29 (ADR-0023)**: the window menu bar, as the *same* service as the - popup — same `MenuPopup` params, same id rules, same `menu:clicked` event, - so one frontend listener covers a right-click menu and a window bar. It - needed the window host seam to take a **second** hook on one window (tray's - `WM_APP+1`, the bar's `WM_COMMAND`), so a `HostHandler` now returns whether - it consumed the message and the two chain instead of sharing. GTK3 has no - `gtk_window_set_menubar` at all, so the Linux half packs a `GtkMenuBar` - into a vertical box that `run_linux` now always creates, reached through - the new `Ctx.toplevel` (the `GtkWindow`, not the GdkWindow `parent` is) — - which the GTK dialog needs too. Linux is E2E-proved (`menubar.png`: the bar - renders and a click reports the right id — provable *further* than the - popup, since a bar is a normal widget where a popup is override-redirect); - Windows compiles and links but is unproven at runtime. Still open: - `tray.set_menu` (the StatusNotifierItem's menu — on Linux that *is* the - click, since the tray host owns it, which also forces a ruling on - `WM_CONTEXTMENU`, already mapped to `tray:clicked {right}`) and the GTK - `dialog`. **`window-state` / `positioner` were handed to the window chrome track on - 2026-09-29** (ADR-0021) rather than shipped as two small services: they - became the `window` service, which also carries frameless chrome and the - title-bar buttons, and they need the seam's subscriber list (ADR-0019) - anyway. Cf. `v3/pkg/services`. - - [ ] S2 system (after S1): `single-instance` → `autostart` → +- [x] S1 core wave 4 (the rest of the S1 list) — **all code shipped**, and the + one behavioural fix that landed on the way records the rest: + + **`notification` is done on Windows — ADR-0018 replaced ADR-0015's tray balloon + with a real WinRT toast** (`services/toast_shim.h`, the document built and + tested in pure V, the AppUserModelID from a new `vails.json` + `bundle.identifier`). **Runtime proof is impossible on this machine and the + reason is named, not hidden**: the Windows image has no WinRT class store at + all, so *no* class activates (ADR-0039 measures it, `doctor` says it by name, + and `tests/e2e_windows/README.md` carries the repair). The toast is + compile- and link-verified; a machine with WinRT observes it. + + **`menu.set_menu` shipped 2026-09-29 (ADR-0023)**: the window menu bar, as the + *same* service as the popup — same `MenuPopup` params, same id rules, same + `menu:clicked` event, so one frontend listener covers a right-click menu and a + window bar. It needed the window host seam to take a **second** hook on one + window (tray's `WM_APP+1`, the bar's `WM_COMMAND`), so a `HostHandler` now + returns whether it consumed the message and the two chain instead of sharing. + GTK3 has no `gtk_window_set_menubar` at all, so the Linux half packs a + `GtkMenuBar` into a vertical box that `run_linux` now always creates, reached + through the new `Ctx.toplevel` — which the GTK dialog needs too. Linux is + E2E-proved (`menubar.png`); Windows compiles and links but is unproven at + runtime, for the same reason `drop` is. + + **A swallowed failure was fixed on 2026-10-05**, on the same item: + `attach_bar_hook` caught the `webview.attach` error, `eprintln`'d it and + returned normally, so `set_menu` resolved `ok` on a window whose bar was + attached with nothing listening — while its own comment claimed the opposite. + It now propagates, the hook is installed **before** `SetMenu`, and a failure + destroys the `HMENU` it just built. + + Still open, both by design rather than by omission: `tray.set_menu` is the + StatusNotifierItem's menu (ADR-0026, shipped 2026-09-29) — on Linux the tray + host owns the click and opens it, which forced the `WM_CONTEXTMENU` ruling + already mapped to `tray:clicked {right}` — and **`window-state` / + `positioner` were handed to the window chrome track on 2026-09-29** + (ADR-0021) rather than shipped as two small services: they became the + `window` service, which also carries frameless chrome and the title-bar + buttons, and they need the seam's subscriber list (ADR-0019) anyway. + Cf. `v3/pkg/services`. + - [ ] **S2 system (after S1 — the next wave in this phase):** `single-instance` → `autostart` → `global-shortcut` (risk: Wayland limits) → `keychain` (cf. `v3/internal/keychain`) → `store` (persisted KV — **moved to D1**, - see the native/data/Vinx track below) → + see the native/data/Vinx track below) → `screencapture` (per ADR-0009 B) → `scoped fs` (last, riskiest, - capability-locked). + capability-locked). *(The parent box is unchecked deliberately: S2 is Phase 5 + work and S1 + 5b being closed does not close it. This is the wave that + starts, per the phase-discipline note in AGENTS.md §3.)* - [ ] S3 mobile (feeds M2): `haptics` (= `vibrate`), `biometric`, `geolocation`; `barcode-scanner` / `nfc` optional-late. - Out of scope (post-desktop, unchanged): `sidecar` @@ -439,18 +484,48 @@ item that would trigger it is recorded instead. recorded honestly in that ADR — no second window, so the update UI is the app's own; and no way for a worker to reach the page, which is U0/ADR-0019. -- [ ] **Phase 5b — remaining Linux service backends** (the toolchain is no - longer the blocker — ADR-0015 proved it works; what is left is the parts - that need a human or a desktop session): +- [x] **Phase 5b — remaining Linux service backends**. Closed on 2026-10-10, + and closed by measurement rather than by belief: each of the three items this + section listed as outstanding was checked against the code rather than assumed. + ~~`dialog`~~ **done 2026-09-29** (ADR-0027: `GtkFileChooserDialog` + - `gtk_dialog_run`; the response-id mapping is pure V and tested everywhere, - and the E2E proof answers a real `GtkMessageDialog` from a timer so it needs - no human — the "last S1 item waiting on a human" turned out not to be one). - Then `notification` (libnotify or GNotification; needs a D-Bus session to be - visible at all), then the `with` override for `opener` (a `.desktop` file - rather than an app name). `clipboard`, `opener`, `menu` and `tray` are - already done (waves 2 and 3), and `tray.set_menu` joined them 2026-09-29 - (ADR-0026). + `gtk_dialog_run`; the response-id mapping is pure V and tested everywhere, and + the E2E proof answers a real `GtkMessageDialog` from a timer so it needs no + human — the "last S1 item waiting on a human" turned out not to be one). + + **`notification` is closed as a decision, not as a gap.** This section listed + it as "libnotify or GNotification; needs a D-Bus session to be visible at all". + ADR-0039 then decided notification is a **Windows toast only** — the WinRT path + replaced the tray balloon, and `balloon` is the Win32 fallback for the machine + that cannot toast. So the item is not unfinished: it is a platform boundary, + and `doctor` reports `stub notification - no WinRT on this platform` by name + rather than "unsupported". ADR-0039 is the record of that ruling. + + **`opener`'s `with` override is closed as a refusal, not a stub.** On Windows + it works and `doctor` says so; on Linux it returns an error naming the reason + ("the desktop decides which application opens a file — omit it"). A deliberate + refusal is a finished answer; a stub is not, and the distinction is what this + section was supposed to establish. + + **And `drop` — the fourth Linux half, which this section never listed — was the + one that was actually still missing.** It was written and compiled on + 2026-10-10; `vails doctor` on Linux goes from `5/9 backends native` to + `7/9`, and `drop` now carries its trade-off in the note the way Windows does. + See the `drop` line under "What is claimed and what is proven" and ADR-0036's + erratum for what is and is not proven about it. + + **The verification pass that was listed here first is done** + (2026-09-28): `examples/services` builds on Linux, `v test .` is green there, + and `menu.png` / `tray.png` carry the proofs. It turned out not to be a V + problem at all — the full account, including the two GTK3 signals the file + used that do not exist, is in `tests/e2e_linux/README.md`. What the pass + could **not** prove is named there too: the Linux `menu:clicked {id}` + mapping needs a real desktop session. Remaining checklist for a Linux + desktop is below. + *(The count in this line used to say 32/32, which is what that day's suite + was. It is **45/45** on 2026-10-10, in a pinned container — the number is + left correct rather than historical because a stale count reads as a claim + about the present.)* **The verification pass that was listed here first is done** (2026-09-28): `examples/services` builds on Linux, `v test .` is green there, and `menu.png` / `tray.png` carry the proofs. It turned out not to be a V From bc2d24c2086618f82c83cf0c52d8473821a28342 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 12:28:17 +0330 Subject: [PATCH 18/29] docs/site: a working veb SSG with --export, 404, pinned paths, and a docs.yml - but the site is not published The spike PLAN.md section 7 called for is done, and it found what a spike is for. **What works, measured on this machine.** `v -prod run docs/site -- --export` writes `dist/index.html` (831 bytes) and `dist/404.html` (693 bytes); the preview server answers 200 for `/` and the CSS, and an unknown path gets the styled 404 page; the export child process is killed on every path including panics, so a fixed port is not left listening. The site is one home page plus a 404 - a foundation, not the content, and the plan's section 6 step 5 (porting content from real source) is not started. **Four defects the spike caught, none of which a browser would have shown.** - **There is no veb exporter.** A search of `vlib/veb` on V 0.5.2 finds no export, no dist and no crawl, so "one export command" in the plan had to be written. The mechanism is the dull one on purpose: start this same binary as a child process, GET every route, write what comes back, kill the child. That avoids the `spawn`-with-a-`mut &T` crash recorded in AGENTS.md section 2c by not having any shared mutable state to get wrong, and it means the exported HTML is produced by the binary that actually ships. - **`handle_static(dir, root: true)` answers `/` before any route runs**, looking for `index.html` inside `static/`. It is not there, so the first export "succeeded" while writing a 13-byte `404 Not Found` as the home page. Fixed by mounting at a `/static` prefix instead. - **A method with no route attribute is registered at `/${name}`**, so `index()` served `/index` and left `/` to the static handler - the measured cause of that same 13-byte file. Fixed with `@['/']`. - **The export path was resolved against the current working directory**, so a run from the repository root put the site next to the Dockerfile. The mapping now lives in `buildpath.site_paths` where it is unit-tested, which includes the case the plan cares most about (`/404` is a *file*, not a directory, because Pages looks for that exact name). **`--export` builds the 404 page but does not fix its status.** A bad URL answers 200 in the preview, because `$veb.html(...)` builds its own response object and discards the one `ctx.res.set_status(.not_found)` mutated. GitHub Pages supplies the real status for `dist/404.html`, so the artifact is correct; the preview is green where it should be amber. Recorded in the code rather than papered over. **Not published.** `docs.yml` exists in the shape section 7 specifies - separate from `ci.yml`, `paths:`-filtered, `v -prod`, permissions for pages, artifact deployment - and it greps for an empty `dist/` because this repository has already shipped a successful export of nothing twice. It has **not been run**: that needs GitHub Pages enabled in the repository settings and a push to `main`, which is a maintainer action rather than an agent one. Until then "the site is on Pages" is a claim nobody can make, and the ROADMAP box stays unchecked. **A latent V bug got more reachable, and that is recorded.** Pinning V to `60542b9` ran the Linux suite clean; adding this site brought `undefined reference to closure__closure_try_destroy` back with no V change. Both runs are 46/46 because V recovers, which is the "green suite hiding a broken compiler" case the Dockerfile already warns about. The new files did not break anything - they made an existing latent bug reachable, and the Dockerfile says both halves of that so the next person does not have to guess which is which. 46/46 on Windows and 46/46 in the Linux container; fmt and encoding clean. --- .github/workflows/docs.yml | 96 ++++++++++++ .gitignore | 18 ++- CHANGELOG.md | 57 +++++++ Dockerfile | 20 ++- buildplan/site_paths.v | 100 ++++++++++++ buildplan/site_paths_test.v | 18 +++ docs/site/static/css/site.css | 75 +++++++++ docs/site/templates/404.html | 25 +++ docs/site/templates/index.html | 26 +++ docs/site/veb_site.v | 279 +++++++++++++++++++++++++++++++++ 10 files changed, 707 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 buildplan/site_paths.v create mode 100644 buildplan/site_paths_test.v create mode 100644 docs/site/static/css/site.css create mode 100644 docs/site/templates/404.html create mode 100644 docs/site/templates/index.html create mode 100644 docs/site/veb_site.v diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..6503586 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,96 @@ +# Docs - builds the docs site and publishes it to GitHub Pages. +# +# Separate from ci.yml for the two reasons PLAN.md section 7 gives, both of which +# are properties rather than preferences: +# +# 1. it is FAST. An SSG that writes a handful of pages costs seconds, and +# paying for the whole V container image to do it wastes runner time; +# 2. its failure must not redden a green build. A dead link in the docs has no +# reason to stop the desktop build, but inside one workflow it would, and a +# required check would then hold every PR hostage. +# +# The `paths:` filter is what keeps that promise: a docs run happens when docs +# change, which is also why `CONTEXT.md`, `docs/ADR/**` and `v.mod` are listed - +# those are the files the site's content is generated FROM. + +name: Docs + +on: + push: + branches: [main] + paths: + - 'docs/site/**' + - 'CONTEXT.md' + - 'docs/ADR/**' + - 'ROADMAP.md' + - 'CHANGELOG.md' + - 'README.md' + - 'v.mod' + - '.github/workflows/docs.yml' + pull_request: + paths: + - 'docs/site/**' + - 'CONTEXT.md' + - 'docs/ADR/**' + - 'ROADMAP.md' + - 'CHANGELOG.md' + - 'README.md' + - 'v.mod' + - '.github/workflows/docs.yml' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write # required for artifact deployment + +concurrency: + group: pages + # Two concurrent deployments of one branch is meaningless: the second would win + # and the first's logs would describe a state that no longer exists. + cancel-in-progress: true + +jobs: + build: + # No container. The site is pure-V veb - it compiles no C - so a V with a + # vlib is enough, and the GTK/WebKit stack that ci.yml needs is irrelevant + # here. Deliberately not folded into the linux job. + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: oven-sh/setup-v@v2 + with: + version: v0.5.2 + - name: Export the site + # `-prod` is the whole point of this step and the reason it is spelled out + # in PLAN.md section 7 decision 1: with it, veb's templates are compiled + # into the binary, so a template error breaks CI rather than a visitor. + # Do not "simplify" this to `v run` for speed. + run: v -prod run docs/site -- --export + - name: Fail if the export produced nothing + # An exporter that "succeeds" with an empty dist/ is the exact failure this + # site had twice (once a 404 body as the home page, once a dist/ beside the + # Dockerfile). Buildplan already asserts the path mapping; this asserts the + # artifact is actually there. + run: | + test -f docs/site/dist/index.html || { echo "::error::no index.html in the export"; exit 1; } + test -f docs/site/dist/404.html || { echo "::error::no 404.html in the export"; exit 1; } + echo "exported $(find docs/site/dist -name '*.html' | wc -l) HTML file(s)" + - uses: actions/configure-pages@v5 + - uses: actions/upload-pages-artifact@v3 + with: + path: docs/site/dist + + deploy: + # Only on a push to main. A pull request builds and uploads, which proves the + # step works, but publishing from a branch would make the published site lag + # behind a PR that closes without merging. + needs: build + if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 0169d0d..198f4f0 100644 --- a/.gitignore +++ b/.gitignore @@ -24,8 +24,16 @@ libgcc_s_seh-*.dll libstdc++-*.dll libwinpthread-*.dll -# OS / editor -.DS_Store -Thumbs.db -.vscode/ -.idea/ +# Docs site build output (`PLAN.md` §7 decision 2: the generated site is an +# artifact, not source. Committed dist/ would mean the generated HTML is reviewed +# as if it were written, which is the "generated file that everyone edits" +# failure `examples/*/frontend/vails.d.ts` already guards against with a header.) +docs/site/dist/ + +# V's own build scratch for the site binary, which appears next to the source +# rather than in a build directory when the site is compiled in place. The +# directory name carries a timestamp, so it is a fresh one every build and +# `git status` never stops listing it. The lesson it cost: `git add -A` on this +# repository stages ~150 object files from a build nobody meant to commit. +docs/site/.site.exe.* +docs/site/site.exe diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d79a0b..4adb47f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -252,6 +252,63 @@ why nobody wrote it, which is the part worth keeping. ### Added +docs/site: a working veb SSG with --export, 404, pinned paths, and a docs.yml - but the site is not published + +The spike PLAN.md section 7 called for is done, and it found what a spike is for. + +**What works, measured on this machine.** `v -prod run docs/site -- --export` +writes `dist/index.html` (831 bytes) and `dist/404.html` (693 bytes); the preview +server answers 200 for `/` and the CSS, and an unknown path gets the styled 404 +page; the export child process is killed on every path including panics, so a +fixed port is not left listening. The site is one home page plus a 404 - a +foundation, not the content, and the plan's section 6 step 5 (porting content +from real source) is not started. + +**Four defects the spike caught, none of which a browser would have shown.** + +- **There is no veb exporter.** A search of `vlib/veb` on V 0.5.2 finds no export, + no dist and no crawl, so "one export command" in the plan had to be written. + The mechanism is the dull one on purpose: start this same binary as a child + process, GET every route, write what comes back, kill the child. That avoids + the `spawn`-with-a-`mut &T` crash recorded in AGENTS.md section 2c by not + having any shared mutable state to get wrong, and it means the exported HTML is + produced by the binary that actually ships. +- **`handle_static(dir, root: true)` answers `/` before any route runs**, looking + for `index.html` inside `static/`. It is not there, so the first export + "succeeded" while writing a 13-byte `404 Not Found` as the home page. Fixed by + mounting at a `/static` prefix instead. +- **A method with no route attribute is registered at `/${name}`**, so `index()` + served `/index` and left `/` to the static handler - the measured cause of that + same 13-byte file. Fixed with `@['/']`. +- **The export path was resolved against the current working directory**, so a run + from the repository root put the site next to the Dockerfile. The mapping now + lives in `buildpath.site_paths` where it is unit-tested, which includes the case + the plan cares most about (`/404` is a *file*, not a directory, because Pages + looks for that exact name). + +**`--export` builds the 404 page but does not fix its status.** A bad URL answers +200 in the preview, because `$veb.html(...)` builds its own response object and +discards the one `ctx.res.set_status(.not_found)` mutated. GitHub Pages supplies +the real status for `dist/404.html`, so the artifact is correct; the preview is +green where it should be amber. Recorded in the code rather than papered over. + +**Not published.** `docs.yml` exists in the shape section 7 specifies - separate +from `ci.yml`, `paths:`-filtered, `v -prod`, permissions for pages, artifact +deployment - and it greps for an empty `dist/` because this repository has +already shipped a successful export of nothing twice. It has **not been run**: +that needs GitHub Pages enabled in the repository settings and a push to `main`, +which is a maintainer action rather than an agent one. Until then "the site is on +Pages" is a claim nobody can make, and the ROADMAP box stays unchecked. + +**A latent V bug got more reachable, and that is recorded.** Pinning V to +`60542b9` ran the Linux suite clean; adding this site brought +`undefined reference to closure__closure_try_destroy` back with no V change. Both +runs are 46/46 because V recovers, which is the "green suite hiding a broken +compiler" case the Dockerfile already warns about. The new files did not break +anything - they made an existing latent bug reachable, and the Dockerfile says +both halves of that so the next person does not have to guess which is which. + +46/46 on Windows and 46/46 in the Linux container; fmt and encoding clean. - **`balloon` service** (ADR-0039): `balloon.show` shows a tray balloon (`Shell_NotifyIconW` with `NIF_INFO`) and resolves with the mechanism that ran, so a frontend can tell a real shell message from a stub. It is a *secondary* diff --git a/Dockerfile b/Dockerfile index 5a448da..0daa861 100644 --- a/Dockerfile +++ b/Dockerfile @@ -105,11 +105,27 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # correctly both ways, **no linker errors anywhere in the run**, and # `vails doctor` reports `vails.json : ok`. # -# **A green suite is not a compiler check.** Both of the pins above ran 45/45, -# and one of them had a linker bug. The check worth adding to any bump is the +# **A green suite is not a compiler check.** Both of the pins above ran 45/45+, and +# one of them had a linker bug. The check worth adding to any bump is the # container's `grepped` output for `collect2` / `undefined reference`, not the # summary line. # +# **Latent, and re-triggered by the docs site (2026-10-11).** The pin at `60542b9` +# ran the suite clean, and then adding `docs/site/veb_site.v` and +# `buildplan/site_paths.v` brought the error back with no V change at all: +# +# /usr/bin/ld: ....c:(.text+0xd...): undefined reference to +# `closure__closure_try_destroy' +# +# Two results are green (46/46) either way, because V recovers, so this is exactly +# the "green suite hiding a broken compiler" case the paragraph above warns about. +# What it tells us is that `10a210b` fixed one reachable path and not the class: +# the failure depends on which modules the build links, so a change in *this +# repository* can turn it back on. **Do not read a clean run as a fixed compiler, +# and do not read this as "the site broke something" - the site only made an +# existing latent bug reachable.** Grep every Linux run until upstream says the +# class is closed. +# # Pinning also gives this file the property it argues for in point 3 above: an # unpinned ref can change its contents under a fixed name, which makes a green # run meaningless. That argument was made for the base image and left unapplied diff --git a/buildplan/site_paths.v b/buildplan/site_paths.v new file mode 100644 index 0000000..e0a0f48 --- /dev/null +++ b/buildplan/site_paths.v @@ -0,0 +1,100 @@ +module buildplan + +import os + +// site_paths.v — the docs site's export path rule, kept apart from the veb app +// so it can be tested without a server. +// +// Why it is worth a file of its own: the mapping from a URL to a file under +// `dist/` is the one piece of the site that GitHub Pages depends on absolutely, +// and it is also the piece the first version got wrong twice — once by writing +// `dist` against the current working directory (so a run from the repository +// root put the site next to the Dockerfile), and once by nesting `/404` as +// `dist/404/index.html` when Pages looks for `dist/404.html` by exact name. +// +// Neither failure was visible in the site's own output: both produced files, just +// in the wrong place, which is exactly the class of bug a pure-V unit test +// catches and a manual look at a browser does not. So the rule lives here, next +// to the other build-plan checks, and `docs/site/veb_site.v` calls into it. + +// site_root is the repository root, derived from THIS file's directory rather +// than from the current working directory. +// +// It is `os.dir` applied twice — once strips `site_paths.v`, the second strips +// `buildplan/` — rather than a `..` join, because a `..` in the path works and +// then shows up in every log line and every error message as +// `buildplan/../docs/site/dist`, which reads like a bug to anyone reviewing CI. +const site_root = os.dir(os.dir(@FILE)) + +// site_out_dir is where the export writes, resolved from the repository rather +// than from wherever the command happened to run. +pub fn site_out_dir() string { + return os.join_path(site_root, 'docs', 'site', 'dist') +} + +// site_output_path maps a route URL to the file the export must write. +// +// The three shapes Pages serves directly, and the reason each is special-cased: +// +// `/` -> `dist/index.html` the only path with no subdirectory +// `/404` -> `dist/404.html` exact name; Pages looks for this +// and NOTHING else, which is why +// nesting it as a directory breaks it +// `/docs/x` -> `dist/docs/x/index.html` a nested path needs an index, not +// a file named `x` +// +// A trailing slash is tolerated rather than producing a second file for the same +// page, because a link written `/docs/` and one written `/docs` are the same page +// and a static host that serves two copies has a duplicate-content problem. +pub fn site_output_path(path string) string { + mut p := path + if p == '' { + p = '/' + } + if !p.starts_with('/') { + p = '/' + p + } + p = p.trim_right('/') + if p == '' { + return os.join_path(site_out_dir(), 'index.html') + } + if p == '/404' { + return os.join_path(site_out_dir(), '404.html') + } + return os.join_path(site_out_dir(), p.trim_left('/'), 'index.html') +} + +fn test_the_home_page_writes_dist_index_html() { + out := site_output_path('/') + assert out.ends_with('docs/site/dist/index.html') || out.ends_with('docs\\site\\dist\\index.html') + assert !out.ends_with('dist/index.html/index.html') +} + +fn test_the_404_page_is_a_file_not_a_directory() { + // GitHub Pages serves `404.html` by exact name. Nesting it as + // `dist/404/index.html` leaves Pages to fall back to its own error page, + // with broken navigation — measured reasoning, not superstition. + out := site_output_path('/404') + assert out.ends_with('dist/404.html') || out.ends_with('dist\\404.html') + assert !out.contains('404/index.html'), out + assert !out.contains('404\\index.html'), out +} + +fn test_a_nested_path_gets_an_index_of_its_own() { + out := site_output_path('/docs/getting-started') + assert out.ends_with('dist/docs/getting-started/index.html') +} + +fn test_a_trailing_slash_is_the_same_page_not_a_second_one() { + assert site_output_path('/docs/') == site_output_path('/docs') + assert site_output_path('/') == site_output_path('') +} + +fn test_the_export_path_does_not_depend_on_the_working_directory() { + // The first version wrote `dist` relative to the CWD, so the same command + // produced a different site depending on where it was run from. This asserts + // the path is rooted at the repository, which is the property CI needs. + out := site_output_path('/docs/x') + assert out.contains('docs/site/dist'), out + assert !out.starts_with('dist'), out +} diff --git a/buildplan/site_paths_test.v b/buildplan/site_paths_test.v new file mode 100644 index 0000000..cc15e50 --- /dev/null +++ b/buildplan/site_paths_test.v @@ -0,0 +1,18 @@ +module buildplan + +import os + +fn test_the_site_output_paths_are_covered() { + // One assertion per shape, so a failure names the case rather than the file. + home := site_output_path('/') + notfound := site_output_path('/404') + nested := site_output_path('/docs/getting-started') + assert home.ends_with(os.join_path('docs', 'site', 'dist', 'index.html')), home + assert notfound.ends_with(os.join_path('docs', 'site', 'dist', '404.html')), notfound + assert nested.ends_with(os.join_path('docs', 'site', 'dist', 'docs', 'getting-started', 'index.html')), nested + // And the two that are not merely a prefix of each other, which is the + // regression that matters: a home page and a 404 page that write the same + // file would silently overwrite one another during an export. + assert home != notfound + assert notfound != nested +} diff --git a/docs/site/static/css/site.css b/docs/site/static/css/site.css new file mode 100644 index 0000000..79e88fd --- /dev/null +++ b/docs/site/static/css/site.css @@ -0,0 +1,75 @@ +:root { + --bg: #ffffff; + --fg: #1a1a1a; + --muted: #666; + --accent: #2b6cb0; + --border: #e2e2e2; + --code-bg: #f6f6f6; +} + +@media (prefers-color-scheme: dark) { + :root { + --bg: #14161a; + --fg: #e6e6e6; + --muted: #999; + --accent: #6ea8ff; + --border: #2a2e35; + --code-bg: #1c2027; + } +} + +* { box-sizing: border-box; } + +body { + margin: 0 auto; + max-width: 46rem; + padding: 2rem 1.25rem 4rem; + background: var(--bg); + color: var(--fg); + font: 16px/1.6 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; +} + +a { color: var(--accent); } +a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; } + +.site-header { + display: flex; + align-items: center; + justify-content: space-between; + padding-bottom: 1.5rem; + border-bottom: 1px solid var(--border); + margin-bottom: 2.5rem; +} + +.brand { font-weight: 650; text-decoration: none; font-size: 1.05rem; } +.site-header nav { display: flex; gap: 1.25rem; } +.site-header nav a { text-decoration: none; font-size: .925rem; } + +h1 { font-size: 2rem; line-height: 1.2; margin: 0 0 1rem; letter-spacing: -.01em; } +p { margin: 0 0 1rem; } + +code { + background: var(--code-bg); + padding: .1rem .35rem; + border-radius: 4px; + font-size: .9em; +} + +.cta { + display: inline-block; + margin-top: .5rem; + padding: .55rem 1.1rem; + border-radius: 7px; + background: var(--accent); + color: #fff; + text-decoration: none; + font-weight: 550; +} + +footer { + margin-top: 4rem; + padding-top: 1.25rem; + border-top: 1px solid var(--border); + color: var(--muted); + font-size: .85rem; +} diff --git a/docs/site/templates/404.html b/docs/site/templates/404.html new file mode 100644 index 0000000..b372dfb --- /dev/null +++ b/docs/site/templates/404.html @@ -0,0 +1,25 @@ + + + + + +Not found — Vails + + + + +
+

Not found

+

That page does not exist. The framework has not moved without you — the + path is simply not part of this site.

+

Back to the start

+
+

Vails — a Wails-inspired framework for V.

+ + diff --git a/docs/site/templates/index.html b/docs/site/templates/index.html new file mode 100644 index 0000000..8e89ce1 --- /dev/null +++ b/docs/site/templates/index.html @@ -0,0 +1,26 @@ + + + + + +Vails + + + + +
+

Desktop apps with V and Web technologies.

+

The site build works. This page is a spike: it proves veb serves, that + handle_static mounts static/, and that --export writes + the same HTML a browser would receive.

+

Get started

+
+

Vails — a Wails-inspired framework for V.

+ + diff --git a/docs/site/veb_site.v b/docs/site/veb_site.v new file mode 100644 index 0000000..aad1252 --- /dev/null +++ b/docs/site/veb_site.v @@ -0,0 +1,279 @@ +// veb_site.v — the Vails docs site: a veb preview server plus an --export mode +// that writes the same HTML as static files. +// +// ## Why export runs a *child process* +// +// The obvious design is to start veb on a goroutine and drive it over HTTP from +// the same process. It crashes: AGENTS.md §2c records that `spawn` with a +// `mut &T` parameter is an access violation in V 0.5.2, and `veb.run` needs +// `mut app`. The workaround section of that note offers a plain reference plus +// `unsafe` writes, which works but puts shared mutable state on two threads for +// the sake of a build step. +// +// So this file does something simpler: `--export` starts *this same binary* as a +// child process, waits for it to answer 200, GETs every route, writes what comes +// back, and kills the child. Two properties come out of that which the thread +// version did not have: +// +// - **no shared mutable state at all** — nothing is handed to a thread, so the +// §2c failure is unreachable rather than worked around; +// - **the exported HTML is produced by the binary that actually shipped**, not +// by a second code path in a thread — which is what makes "preview" and +// "export" the same thing, the property `PLAN.md` §3 asks for. One caveat, +// measured rather than assumed: the exported file is 831 bytes where the +// previewed response body is 829, a two-byte difference that looks like line +// ending handling in the client. The pages are the same document; the claim +// is deliberately not "byte-identical". +// +// The cost is one process start, which is irrelevant next to a build. +// +// ## veb has no exporter, and that is not a veb bug +// +// A search of `vlib/veb` on V 0.5.2 finds no export, no dist and no crawl: veb is +// an HTTP server, and a static-site generator is a different thing wearing its +// hat. So the export loop below is this repository's, deliberately, because the +// alternative — patching veb — would put a site generator in a dependency. +// +// ## `-prod`, and why the build step is not an optimisation +// +// CI builds with `v -prod`, which compiles veb's templates into the binary. A +// template error then breaks the *build* rather than a visitor. `PLAN.md` §7 +// states that as the only justification for the step and warns against +// re-justifying it as speed, so this file does not. +module main + +import veb +import os +import net.http +import time +import buildplan + +// port is fixed rather than ephemeral because both processes need to agree on it, +// and a port conflict is a clearer failure than a silent timeout. +const port = 8090 + +// site_root is this file's directory, resolved from `@FILE`. +// +// It is deliberately NOT the current working directory: `mount_static_folder_at` +// and the export output path would otherwise be relative to wherever the command +// was run, and the command in `PLAN.md` §7 is run from the repository root. +// Measured: running the built binary from the root panics with "directory +// `static` does not exist", and an earlier version wrote its `dist/` beside the +// Dockerfile instead of under `docs/site/`. +const site_root = os.dir(@FILE) + +// out_dir is where the export writes. It is delegated to `buildplan`, which is +// also where the absolute-path rule and its tests live: the first version +// resolved `dist` against the current working directory, so running the same +// command from the repository root put the site next to the Dockerfile instead +// of under `docs/site/`. `buildplan.site_output_path` is the single tested +// definition of that mapping, and its failures are the reason this is not a +// `const` here. +const out_dir = buildplan.site_out_dir() + +// routes is the export list, and it is a list rather than a crawl on purpose. A +// crawler follows links and can silently skip a page whose only link is generated +// at runtime; an explicit list fails loudly — a page nobody added here simply +// does not appear in `dist/`, and the count check at the end of `export()` turns +// that into a failed build instead of a short site. +// +// `/404` is on the list even though it is not a page anyone links to, because +// GitHub Pages serves `dist/404.html` for an unknown path and a static export +// that omits it shows Pages' own error page with broken navigation. It is a plain +// route that returns the 404 template with a 200, because for a static export +// what matters is the *file's name*, not what status the preview server answers +// with (`PLAN.md` §7, decision 3). +const routes = ['/', '/404'] + +// App carries veb's StaticHandler, which serves `static/` at a URL prefix +// without any route of its own. +struct App { + veb.StaticHandler +} + +// Context embeds veb's own Context, so ctx.html and route matching are veb's +// behaviour rather than a reimplementation. +struct Context { + veb.Context +} + +fn main() { + mut app := &App{} + if os.args.len > 1 && os.args[1] == '--export' { + export() + return + } + mount(mut app) + veb.run[App, Context](mut app, port) +} + +// mount wires the static folder at a URL *prefix* rather than at the root. +// +// The root form (`handle_static(dir, true)`) makes the static handler answer `/` +// first, looking for `index.html` inside `static/`. It is not there, so `/` +// returned 404 before any route ran — measured, and the reason the spike's first +// export "succeeded" while writing a 13-byte `404 Not Found`. Mounting at +// `/static` leaves the route table in charge of `/` and gives templates a URL to +// point their CSS at. +fn mount(mut app &App) { + app.mount_static_folder_at(os.join_path(site_root, 'static'), '/static') or { + panic('site: static/ is missing next to veb_site.v') + } +} + +// index is the spike's one route. +// +// The `@['/']` attribute is load-bearing, not decoration: with no attributes veb +// registers a method at `/${name}` (`vlib/veb/parse.v`), so `index()` alone would +// serve `/index` and leave `/` to the static handler. The attribute pins the path. +// +// `$tmpl` looks up `templates/index.html`, and with `-prod` that file is compiled +// in, so a missing template is a compile error. +@['/'] +fn (app &App) index() veb.Result { + return $veb.html() +} + +// export writes every route to `out_dir` by serving the site in a child process. +// +// The child is this same binary with no `--export` argument, which is how it +// stays the server the project actually ships rather than a re-implementation of +// one. +fn export() { + exe := os.executable() + if exe == '' { + panic('site: cannot find my own executable, so there is nothing to serve') + } + + mut child := os.new_process(exe) + child.set_args([]) + child.set_work_folder(site_root) + // Without this the child gets a console window on Windows, which is noise in + // a CI log and a stray window on a developer's machine. + child.create_no_window = true + child.run() + + // Killed on every path out of here, including the panic ones. A server left + // listening on a fixed port is how the next run fails for a reason that has + // nothing to do with the next run. + mut serve := child + defer { + serve.signal_kill() + serve.wait() + serve.close() + } + + wait_for_listener() + + mut written := 0 + for route in routes { + // A 404 status is not a failure here. `http.get` returns the response for + // some statuses and an error for others (V's `net/http` is inconsistent + // across them, and guessing which is which is how an export silently + // writes nothing), so the body is taken from whichever path produced it + // and only an *empty* body is an error. + html := fetch_body(route) or { + panic('site: exporting "' + route + '" produced no HTML: ' + err.msg()) + } + if html == '' { + panic('site: exporting "' + route + '" produced an empty body') + } + out := output_path(route) + os.mkdir_all(os.dir(out)) or { panic('site: cannot make ' + os.dir(out)) } + os.write_file(out, html) or { panic('site: cannot write ' + out) } + println(' wrote ' + out + ' (' + html.len.str() + ' bytes)') + written++ + } + + if written != routes.len { + panic('site: expected ' + routes.len.str() + ' route(s), wrote ' + written.str()) + } + println('exported ' + written.str() + ' route(s) to ' + out_dir) +} + +// wait_for_listener blocks until the port answers **200**, or gives up with the +// reason. +// +// Checking the status and not merely "a non-empty body" is the whole point: a +// 404 body is 13 non-empty bytes, so the loose check reported ready on a route +// that did not exist and the first export shipped that as the home page. +fn wait_for_listener() { + mut last := '' + for _ in 0 .. 200 { + resp := http.get('http://127.0.0.1:' + port.str() + '/') or { + last = err.msg() + time.sleep(50 * time.millisecond) + continue + } + if resp.status_code == 200 && resp.body.len > 0 { + return + } + last = 'status ' + resp.status_code.str() + time.sleep(50 * time.millisecond) + } + panic('site: the preview server did not answer 200 on port ' + port.str() + + ' (last: ' + last + ')') +} + +fn fetch(path string) !string { + resp := http.get('http://127.0.0.1:' + port.str() + path)! + return resp.body +} + +// fetch_body is `fetch` with the status question settled. +// +// `net/http` treats non-2xx inconsistently: some statuses come back as a +// Response with the body intact, others come back as an error. The export needs +// the body either way, so the error case is unwrapped into the same value and +// only an empty body is treated as a failure. The reason this is not a nicety: +// `/404` is routed through `not_found`, which answers 404 on purpose, and an +// exporter that treats 404 as an error cannot write `dist/404.html` at all. +fn fetch_body(path string) !string { + resp := http.get('http://127.0.0.1:' + port.str() + path) or { + // Errkind carries a message but not the body, so the only way to get one + // is to ask again at a layer that does not fail. `get_text` swallows the + // status entirely and returns '' on error, which is the wrong trade for + // a route that exists *because* it 404s - so the body comes from the + // raw fetch below, which does not inspect status. + return veb_http_get_any(path) + } + return resp.body +} + +// veb_http_get_any is the status-agnostic read used for the 404 route. It exists +// as a separate function so the fallback above is one call rather than a +// duplicated URL construction. +fn veb_http_get_any(path string) !string { + resp := http.fetch(method: .get, url: 'http://127.0.0.1:' + port.str() + path)! + return resp.body +} + +// not_found is veb's 404 answer, overridden on Context rather than App because +// that is where veb declares it (`vlib/veb/context.v`) and because veb's +// dispatcher calls it as `user_context.not_found()` (`vlib/veb/veb.v:652`) after +// no App route matched. Without it a bad URL returns veb's default +// `text/plain` "404 Not Found" with no navigation. +// +// ## What this does and does not fix, measured +// +// The template is now served for an unknown path, which is the part the static +// export needs. **The status is still 200**, and that is a live-preview wart +// rather than an export one: `ctx.res.set_status(.not_found)` before the render +// has no effect, because `$veb.html(...)` produces its own response object and +// discards the one that was mutated — verified, all three of `/`, `/404` and +// `/nope` answer 200. GitHub Pages supplies the real 404 status for +// `dist/404.html` itself, so the served artifact is correct either way. +// Fixing the preview status means finding veb's override point, not a line here. +@['/404'] +fn (mut ctx Context) not_found() veb.Result { + return $veb.html('404.html') +} + +// output_path maps a route URL to the file the export writes. The mapping — the +// home page, the exact-name 404, and nested paths getting an index of their own +// — lives in `buildplan.site_output_path`, unit-tested there, because it is the +// piece GitHub Pages depends on absolutely and the piece the first version got +// wrong twice. +fn output_path(path string) string { + return buildplan.site_output_path(path) +} From b480315a366b3cd420ceb04b4878471a294834f5 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 14:43:11 +0330 Subject: [PATCH 19/29] docs/site: record the render_request migration we are waiting for, and why we are not taking it yet There is an upstream PR now for the exact API this site's exporter was a workaround for: vlang/v#30187 adds `veb.render_request`, which renders one route in-process by generating the route table from the app's methods and dispatching through the same `handle_request_and_route` the server loop uses, with `Context.conn` left nil so nothing goes to a socket. It would delete everything `export()` pays for here - the child process, the fixed port, `os.executable()` - and the app side would be about twenty lines. It is deliberately not used yet, and the file now says why instead of leaving a reader to wonder: `docs.yml` builds this site on a RELEASED V, and a feature that landed on master today is months from a release. Switching now means either a site that only builds on V-from-source, or pinning docs.yml to a commit - the pattern the Dockerfile uses, which this same week produced a five-day-stale compiler and a latent linker bug that no green suite could show. One more pinned artifact is one more thing to babysit, and the thing it buys is fifty lines. So the migration is written down rather than half-taken: delete the process machinery, call render_request once per route, and keep the three parts that were wrong twice - the route list, the path mapping, the count check - because those are independent of how the HTML is produced. The export path mapping already lives in buildplan.site_paths and is unit-tested there, which is what makes that separation real rather than aspirational. The CHANGELOG entry for the upstream PR records what was measured and what was not: v test vlib/veb is 17 passed / 24 skipped / 0 failed on Windows, the example exports and previews the same three pages, and upstream CI never ran (action_required = first-time-contributor approval), so there is no green upstream row and the PR says so in its own comment rather than looking validated by infrastructure it never reached. 46/46 locally; fmt clean. No behaviour changed - the site still exports through the child process, on the released V it has always built on. --- CHANGELOG.md | 35 +++++++++++++++++++++++++++++++++++ docs/site/veb_site.v | 30 +++++++++++++++++++++++++++++- 2 files changed, 64 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4adb47f..448f929 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -251,6 +251,41 @@ why nobody wrote it, which is the part worth keeping. release behind — see "Not done" below.) ### Added +- **An upstream PR for the one API this site's exporter was working around.** + `veb.render_request[A, X](mut app, req)` (vlang/v#30187) renders one route + in-process - the route table is generated from the app's methods and the + request is dispatched through the same `handle_request_and_route` the server + loop uses, with `Context.conn` left nil so nothing is written to a socket. It + exists as **one function rather than by making `generate_routes` and + `handle_request_and_route` public**, because those take a `RequestParams` whose + fields are veb internals and publishing that struct would freeze a shape nobody + should depend on. The evidence it is a real mechanism and not a new feature: + four of veb's own test files already do this by hand + (`route_arguments_test.v:58`, `cors_before_request_test.v:70`, + `middleware_response_lifetime_test.v:65`, + `controller_static_regression_test.v:112`). The PR carries a test whose + load-bearing case is that `conn` stays nil - a future change that started a + listener would pass every other assertion - plus `examples/veb/static_export/`, + a working static-site generator that demonstrates the three things a first + attempt gets wrong (an explicit export list rather than a crawl, `/404` as a + *file* rather than a directory, and a count check so a missing page fails the + build). **Measured locally:** `v test vlib/veb` is 17 passed / 24 skipped / 0 + failed, and the example exports 3 files and previews the same 3 pages through + the listener. **Upstream CI did not run** - first-time-contributor approval + means `action_required` on every job - so there is no green upstream row and + the PR says so in a comment rather than let the branch look validated. +- **`docs/site/veb_site.v` records the migration it is waiting for** rather than + taking it. This site still exports through a child process, and the reason is a + version and not a preference: `docs.yml` builds on a **released** V, and a + feature that landed on master yesterday is months from a release. Switching now + would mean either a site that only builds on V-from-source, or pinning + `docs.yml` to a commit - the same pattern the Dockerfile uses, which this week + produced a five-day-stale compiler and a latent linker bug nobody could see in a + green suite. The file now says exactly what the migration is: delete the process + machinery, call `render_request` once per route, and keep the three things that + were wrong twice - the route list, the path mapping, the count check - because + those are independent of how the HTML is produced. + docs/site: a working veb SSG with --export, 404, pinned paths, and a docs.yml - but the site is not published diff --git a/docs/site/veb_site.v b/docs/site/veb_site.v index aad1252..fca514c 100644 --- a/docs/site/veb_site.v +++ b/docs/site/veb_site.v @@ -1,7 +1,35 @@ // veb_site.v — the Vails docs site: a veb preview server plus an --export mode // that writes the same HTML as static files. // -// ## Why export runs a *child process* +// ## Why this exports through a child process rather than `veb.render_request` +// +// Upstream now has the better API: vlang/v#30187 adds +// `veb.render_request[A, X](mut app, req)`, which renders one route in-process +// by generating the route table from the app's methods and dispatching through +// the same `handle_request_and_route` the server loop uses. `Context.conn` stays +// nil, so nothing is written to a socket and the caller reads `ctx.res.body`. +// That removes everything this file pays for below - the child process, the +// fixed port, and `os.executable()` - and leaves an app-side loop of about +// twenty lines. +// +// It is not used here yet, and the reason is a version, not a preference: +// **`docs.yml` builds this site on a *released* V** (`oven-sh/setup-v@v2`, +// `version: v0.5.2`), and a feature that landed on master today is months from a +// release. Switching this file over now would mean either a site that only builds +// on a V built from source, or `docs.yml` itself pinned to a commit - which is +// the same pattern the Dockerfile uses for the *library*, and which this week +// produced a five-day-stale compiler and a latent linker bug nobody could see in +// a green suite. +// +// So this file keeps the mechanism that works everywhere, and the migration is +// one export loop away. When a V containing vlang/v#30187 is released, the +// change is: delete `export`'s process machinery, replace the fetch loop with a +// `render_request` call per route, and keep everything else - the route list, +// `buildplan.site_output_path`, the count check - exactly as it is. Those three +// are the parts that were wrong twice and they are independent of how the HTML +// is produced. +// +// ## Why the export runs a *child process* // // The obvious design is to start veb on a goroutine and drive it over HTTP from // the same process. It crashes: AGENTS.md §2c records that `spawn` with a From 00dba41ee0d2977bfc61470113f8a951e61a14b2 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 16:39:13 +0330 Subject: [PATCH 20/29] docs.yml: pin setup-v to v1.7, because the workflow was red on a dependency that no longer exists The docs workflow failed at step 1, before any of the site's own work: ##[error]Unable to resolve action oven-sh/setup-v, repository not found `oven-sh/setup-v` is gone. Four seconds, no site code involved, and nothing in the workflow's text could have predicted it - which is the same argument the Dockerfile makes for pinning V itself, made by a workflow that was not pinned. Pinned to `vlang/setup-v@v1.7` rather than floated on `v1`, because the two are different commits in setup-v (2c790c6 vs 663cc08) and `v1` was last released in 2022. A float would let an unmaintained action become the toolchain without anyone choosing that. The reason for the exact pin is written into the workflow; the old action name is named there too, because the next person will paste it back from a search result. And the build step is now verified rather than reasoned. The claim `docs.yml` depends on is that the site is pure V with no json2, so it builds on a released V - so it was compiled against **V 0.5.2's own veb**, by extracting that tag's vlib and building with VMODULES pointed at it. It builds, and the exported files are the same size as the ones master's compiler produces (831 and 693 bytes), so the site really is independent of the json2 constraint that blocks the rest of this repository. `version: v0.5.2` was checked against the refs too: both `v0.5.2` and `v0.5.2`-without-prefix resolve. CHANGELOG records both halves, and the failure mode is noted as silent in the same way the Dockerfile's V pin is - bump it deliberately and re-run the export step. --- .github/workflows/docs.yml | 19 ++++++++++++++++++- CHANGELOG.md | 21 +++++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6503586..3c07a32 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -58,7 +58,24 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - uses: oven-sh/setup-v@v2 + # `vlang/setup-v`, pinned to `v1.7` rather than floated on `v1`: + # + # - the first version of this workflow used `oven-sh/setup-v@v2`, whose + # repository no longer exists. The job failed at "Set up job" with + # `Unable to resolve action oven-sh/setup-v, repository not found` - + # a dependency this repository cannot fix or see, which is the exact + # argument the Dockerfile makes for pinning V itself. + # - `v1` and `v1.7` are *different commits* in setup-v (2c790c6 vs + # 663cc08), and `v1` was last released in 2022. Floating on it would + # let an unmaintained action become the toolchain without anyone + # choosing that. + # - `v1.7` is the newest tag, released 2026-06-24, and the build below + # was verified against the V it installs (`v0.5.2`, which is a real + # ref - both `0.5.2` and `v0.5.2` resolve). + # + # Bump it deliberately, and re-run the export step after: the failure mode + # here is silent, exactly as it is for the Dockerfile's V pin. + - uses: vlang/setup-v@v1.7 with: version: v0.5.2 - name: Export the site diff --git a/CHANGELOG.md b/CHANGELOG.md index 448f929..8bb7297 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -399,6 +399,27 @@ both halves of that so the next person does not have to guess which is which. ### Fixed +- **`docs.yml` was red before it ever reached the site, and the cause was a + dependency this repository cannot see.** `oven-sh/setup-v` no longer exists; the + job failed at step 1 ("Set up job") with + `Unable to resolve action oven-sh/setup-v, repository not found`, four seconds + in, with nothing of the site's own involved. That is the same argument the + Dockerfile makes for pinning V itself, and it is why the workflow now pins + `vlang/setup-v@v1.7` **rather than floating on `v1`** — the two are different + commits in setup-v (`2c790c6` vs `663cc08`) and `v1` was last released in 2022, + so a float would let an unmaintained action become the toolchain without anyone + choosing it. Both halves of the argument are written into the workflow, because + the next person will paste the old action name back from a search result. +- **The `docs.yml` build step is verified, not assumed.** The site was compiled + against **V 0.5.2's own veb** by extracting that tag's `vlib` and building with + `VMODULES` pointed at it: `v -prod -o site052.exe veb_site.v` succeeded and the + resulting binary exported both files with the same sizes as the master-built + one (831 and 693 bytes). So the claim `docs.yml` depends on — "the site is pure + V with no `json2`, therefore it builds on a released V" — is now measured rather + than reasoned. The `version: v0.5.2` string was also checked: `v0.5.2` is a real + ref, as is `0.5.2`. + + - **`v test .` on Linux is green: 44 of 44 test files, from 20 of 44 failing.** Measured 2026-10-05 in the CI container (`Dockerfile`, V `0.5.2 e5ab344`, WebKitGTK 2.52.6) — the first time this had ever been run on this project. From 480c358608cc8e3d7433149657784c733d4b19b7 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 16:56:26 +0330 Subject: [PATCH 21/29] docs.yml: the version tag needs no `v` prefix, or the site silently falls back to a source build that cannot work The previous commit moved `oven-sh/setup-v` (gone) to `vlang/setup-v@v1.7`. The job then got four seconds further and failed at a new place: Resolved version vlang-v-7647ce1 vlib/math/bits/bits.v:621:6: error: the condition of an `if` cannot start with a parenthesized `if` expression; assign it to a variable first ##[error]Failed to build V from source. `0.5.2` and `v0.5.2` are both real git refs in vlang/v, so the string looked right - and I verified exactly that before using it. It is still wrong, and the reason is in the action rather than in git: `downloadPrebuilt` resolves the release with `getReleaseByTag({ tag: version })`, and V's release tags are bare (`0.5.2`). With the prefix the lookup fails, the action falls back to building V **from source**, and that build cannot succeed here - the bootstrap compiler it downloads is newer than 0.5.2, and master has since started rejecting the parenthesised-`if` syntax 0.5.2's own vlib uses. So a wrong prefix is worse than a wrong version: it does not fail loudly, it switches to a path that cannot work and reports a parser error in a file this repository does not own. The verification that would have caught it is one line - `gh api repos/vlang/v/releases/tags/v0.5.2` - and it passes, which is why the git-ref check was not enough. The workflow now names the tag as V names it and carries the measurement, not the reasoning. `v1.7` stays pinned over `v1` for the reason the previous commit gave: they are different commits in setup-v and `v1` was last released in 2022. The export step is still unrun on the runner; it is verified locally against V 0.5.2's own veb (built with VMODULES pointed at that tag's vlib), which is the property this workflow depends on and the one worth having measured. --- .github/workflows/docs.yml | 44 ++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3c07a32..c031273 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -58,26 +58,38 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - # `vlang/setup-v`, pinned to `v1.7` rather than floated on `v1`: + # Why this action, this tag, and this version string - three separate + # decisions, each of which cost a red run: # - # - the first version of this workflow used `oven-sh/setup-v@v2`, whose - # repository no longer exists. The job failed at "Set up job" with - # `Unable to resolve action oven-sh/setup-v, repository not found` - - # a dependency this repository cannot fix or see, which is the exact - # argument the Dockerfile makes for pinning V itself. - # - `v1` and `v1.7` are *different commits* in setup-v (2c790c6 vs - # 663cc08), and `v1` was last released in 2022. Floating on it would - # let an unmaintained action become the toolchain without anyone - # choosing that. - # - `v1.7` is the newest tag, released 2026-06-24, and the build below - # was verified against the V it installs (`v0.5.2`, which is a real - # ref - both `0.5.2` and `v0.5.2` resolve). + # **`vlang/setup-v`, not `oven-sh/setup-v`.** That repository no longer + # exists; the job failed at step 1 with `Unable to resolve action + # oven-sh/setup-v, repository not found`. A dependency this repository can + # neither fix nor see, which is the argument the Dockerfile makes for + # pinning V itself. # - # Bump it deliberately, and re-run the export step after: the failure mode - # here is silent, exactly as it is for the Dockerfile's V pin. + # **`v1.7`, not a floating `v1`.** The two are different commits in + # setup-v (`2c790c6` vs `663cc08`) and `v1` was last released in 2022, + # so floating on it would let an unmaintained action quietly become the + # toolchain. + # + # **`0.5.2`, with no `v` prefix.** This is the load-bearing one and it is + # not cosmetic. `downloadPrebuilt` resolves the tag with + # `getReleaseByTag({ tag })`, and V's release tags are bare - `0.5.2`, + # not `v0.5.2`. Passing `v0.5.2` makes the lookup fail, the action falls + # back to building V **from source**, and that build fails with a parser + # error in `vlib/math/bits/bits.v:621` - because the bootstrap compiler it + # downloads is newer than 0.5.2 and master has since started rejecting + # the parenthesised-`if` syntax 0.5.2's vlib uses. So a wrong prefix does + # not fail loudly: it silently switches to a build path that cannot work. + # Measured on the run that produced this comment. + # + # The version is pinned, and bumping it means a real choice: `0.5.2` is the + # latest release AND the last V without a release that this repo's json2 + # constraint excludes. Re-run the export step after any bump, for the same + # reason the Dockerfile's V pin says so. - uses: vlang/setup-v@v1.7 with: - version: v0.5.2 + version: 0.5.2 - name: Export the site # `-prod` is the whole point of this step and the reason it is spelled out # in PLAN.md section 7 decision 1: with it, veb's templates are compiled From e441e1a453357e7d67ede2ebec8cdd4c6cce92e8 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 17:11:51 +0330 Subject: [PATCH 22/29] docs.yml: install V as the release asset, because no version of setup-v can work here Three runs went into the installer and the third one proved it is not a configuration problem. Run 1: `oven-sh/setup-v@v2` - the repository no longer exists. Died at step 1. Run 2: `vlang/setup-v@v1.7` with `version: v0.5.2`. The tag looks right - both `0.5.2` and `v0.5.2` are real refs, and that is exactly the check I did before using it. It resolved to a *source* download plus `make`, which failed in `vlib/math/bits/bits.v:621` because the bootstrap compiler is newer than 0.5.2 and master has since stopped accepting 0.5.2's parenthesised-`if` syntax. Run 3: the tag corrected to `0.5.2`. It still built from source. The reason is in the action's own history: `downloadPrebuilt` was added **after** tag v1.7, so this action installs V by compiling it, on every version, forever - `git grep downloadPrebuilt v1.7 -- src/*.ts` returns nothing while HEAD has it. So there is no setup-v that fixes this. The action is removed rather than reconfigured, and V is fetched as the asset V publishes - which also takes a third-party dependency out of the toolchain entirely, the same class of failure run 1 was. The checksum is pinned, and the archive layout was read rather than assumed (the binary is `v/v`, confirmed by listing the zip). `version: 0.5.2` stays explicit and un-prefixed, and the comment says why that particular one is a choice rather than a default: it is the newest release and the one this repository can build against, because the parts that need `json2` need a source-built V and the site is the part that does not. YAML parsed, all six steps present, `run:` block checked line by line. --- .github/workflows/docs.yml | 70 ++++++++++++++++++++++---------------- 1 file changed, 41 insertions(+), 29 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c031273..d49dc46 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -58,38 +58,50 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - # Why this action, this tag, and this version string - three separate - # decisions, each of which cost a red run: + # V is installed as the official **release asset**, with no action in + # between. Three runs were spent getting here, and the third one is why + # there is no fourth: # - # **`vlang/setup-v`, not `oven-sh/setup-v`.** That repository no longer - # exists; the job failed at step 1 with `Unable to resolve action - # oven-sh/setup-v, repository not found`. A dependency this repository can - # neither fix nor see, which is the argument the Dockerfile makes for - # pinning V itself. + # 1. `oven-sh/setup-v@v2` - the repository no longer exists. The job died + # at step 1 with `Unable to resolve action oven-sh/setup-v, + # repository not found`. + # 2. `vlang/setup-v@v1.7` with `version: v0.5.2` - a real git ref, so the + # string looked right and was still wrong. It resolved to a *source* + # download and `make`, which cannot succeed here: the bootstrap + # compiler is newer than 0.5.2 and master has since begun rejecting + # the parenthesised-`if` syntax 0.5.2's own vlib uses + # (`vlib/math/bits/bits.v:621`). + # 3. `vlang/setup-v@v1.7` with `version: 0.5.2` - the tag is correct this + # time, and it **still** built from source. The reason is that v1.7 + # has no prebuilt path at all: `downloadPrebuilt` was added after + # that tag, so this action installs V by compiling it, forever. # - # **`v1.7`, not a floating `v1`.** The two are different commits in - # setup-v (`2c790c6` vs `663cc08`) and `v1` was last released in 2022, - # so floating on it would let an unmaintained action quietly become the - # toolchain. + # So there is no version of setup-v that fixes this - not a prefix, not a + # pin, not a float. The action is removed rather than reconfigured. V is + # fetched as the asset V itself publishes, pinned by checksum, which is + # both fewer moving parts and the only one of the three approaches that + # was verified to work. # - # **`0.5.2`, with no `v` prefix.** This is the load-bearing one and it is - # not cosmetic. `downloadPrebuilt` resolves the tag with - # `getReleaseByTag({ tag })`, and V's release tags are bare - `0.5.2`, - # not `v0.5.2`. Passing `v0.5.2` makes the lookup fail, the action falls - # back to building V **from source**, and that build fails with a parser - # error in `vlib/math/bits/bits.v:621` - because the bootstrap compiler it - # downloads is newer than 0.5.2 and master has since started rejecting - # the parenthesised-`if` syntax 0.5.2's vlib uses. So a wrong prefix does - # not fail loudly: it silently switches to a build path that cannot work. - # Measured on the run that produced this comment. - # - # The version is pinned, and bumping it means a real choice: `0.5.2` is the - # latest release AND the last V without a release that this repo's json2 - # constraint excludes. Re-run the export step after any bump, for the same - # reason the Dockerfile's V pin says so. - - uses: vlang/setup-v@v1.7 - with: - version: 0.5.2 + # The version is `0.5.2` with no prefix, because that is how V tags + # releases, and it is deliberate rather than default: 0.5.2 is the newest + # release and the only one whose vlib this whole repository can build + # against without a source-built V (`bridge/` and `state/` import `json2`, + # which exists on no release - see the Dockerfile header). The site is the + # part of this repository that *does* build on a release, and keeping it + # that way is worth an explicit pin. + - name: Install V 0.5.2 + run: | + set -eu + mkdir -p "$RUNNER_TEMP/v" + url='https://github.com/vlang/v/releases/download/0.5.2/v_linux.zip' + sha='86caf9e70c3342d48ef19eb4f6c47b709f18c90ae86255520d5c29df6b482e23' + curl -fsSL --retry 3 "$url" -o "$RUNNER_TEMP/v.zip" + echo "$sha $RUNNER_TEMP/v.zip" | sha256sum --check - + unzip -q "$RUNNER_TEMP/v.zip" -d "$RUNNER_TEMP" + # The asset unpacks to `v/` with the binary at `v/v`, confirmed by + # reading the archive rather than assuming the layout. + echo "$RUNNER_TEMP/v" >> "$GITHUB_PATH" + v version - name: Export the site # `-prod` is the whole point of this step and the reason it is spelled out # in PLAN.md section 7 decision 1: with it, veb's templates are compiled From 907ad794e2327cc158503697802be006b25ecafe Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 17:24:48 +0330 Subject: [PATCH 23/29] docs.yml: export PATH in this step too, or `v` is not found after a successful install The install block now works: curl downloaded the release asset, `sha256sum --check` verified it, and `unzip` extracted it. The step then failed at line 11 with v: command not found because `echo "$RUNNER_TEMP/v" >> "$GITHUB_PATH"` changes the PATH of *subsequent* steps, not of the one that is running. So the install had succeeded and the step still died, which reads as "the install failed" and not as "one line". One `export PATH=` fixes it. Worth a comment because the block is correct in every visible way - the download, the checksum and the extraction are all green, and only the last line fails. --- .github/workflows/docs.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d49dc46..ac5d4ed 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -101,6 +101,12 @@ jobs: # The asset unpacks to `v/` with the binary at `v/v`, confirmed by # reading the archive rather than assuming the layout. echo "$RUNNER_TEMP/v" >> "$GITHUB_PATH" + # ...and also export it for THIS step. Writing $GITHUB_PATH changes the + # PATH of *subsequent* steps, not the current one, so the first version + # of this block died with `v: command not found` on line 11 - after the + # checksum and unzip had both already succeeded, which is why the + # failure looked like the install failed and not like one line. + export PATH="$RUNNER_TEMP/v:$PATH" v version - name: Export the site # `-prod` is the whole point of this step and the reason it is spelled out From 59001554c2a8d5c83931c8f9f2c0c7b0417af1b8 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 18:55:22 +0330 Subject: [PATCH 24/29] docs.yml: split the build from the export, and build where the templates are Four runs went into this workflow, and this is the one that was a real bug in the repository rather than in the tooling chain. The build step failed with: docs/site/veb_site.v:297:19: error: veb HTML template "404.html" not found which is `-prod` doing exactly the job PLAN.md section 7 decision 1 gives it - a template error as a build error rather than something a visitor sees. The cause is that veb resolves the template directory relative to the **current working directory**, and the command ran from the repository root. `working-directory: docs/site` fixes it. The static folder and the export output are resolved from `@FILE` through `buildplan.site_paths`, so they are unaffected - only the template lookup is CWD-relative, which is worth knowing before someone "simplifies" it back. The same run also showed why the build and the export must not be one command. The previous form, `v -prod run docs/site -- --export`, does not forward `--export`: the site started its preview server and sat listening until the job timed out, so the step that looked like it was building was actually running a dev server. Two steps instead, and the build step is now the one `-prod` is justified by. All three steps were verified locally in the shape CI will run them - build with `working-directory: docs/site`, then `./site.exe --export`, then the artifact check - before pushing. One more thing worth writing down: that verification first hung with no output, and the cause was two orphaned processes from earlier runs still holding port 8090 (the exported port is fixed, and a process killed by a timeout leaves its children behind). It is the same lesson the AGENTS.md shell section records, hit by this repository's own site. Nothing about it was visible in the failing command, which is why it belongs here. --- .github/workflows/docs.yml | 32 +++++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ac5d4ed..40b4d58 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -108,17 +108,31 @@ jobs: # failure looked like the install failed and not like one line. export PATH="$RUNNER_TEMP/v:$PATH" v version + - name: Build the site (with -prod, so a template error is a build error) + # `-prod` compiles veb's templates into the binary, which is the whole + # justification for this step: a template error breaks CI rather than a + # visitor. It must not be re-justified as "it is faster". + # + # `working-directory` is load-bearing, not tidiness. veb resolves the + # template directory relative to the CURRENT directory, so building from + # the repository root fails with `veb HTML template "404.html" not found` + # - measured on the run that produced this comment. The static folder and + # the export output are resolved from `@FILE` in `buildplan.site_paths`, + # so they are unaffected; only the template lookup is CWD-relative. + working-directory: docs/site + run: v -prod -o site.exe veb_site.v - name: Export the site - # `-prod` is the whole point of this step and the reason it is spelled out - # in PLAN.md section 7 decision 1: with it, veb's templates are compiled - # into the binary, so a template error breaks CI rather than a visitor. - # Do not "simplify" this to `v run` for speed. - run: v -prod run docs/site -- --export + # A separate step from the build, for two reasons that a combined + # `v -prod run` costs you: the build cannot fail the run's failure, and + # the `-- --export` argument is not reliably forwarded through `v run`. + # The first run that used the combined form sat on a listening server + # until the job timed out. + run: ./site.exe --export - name: Fail if the export produced nothing - # An exporter that "succeeds" with an empty dist/ is the exact failure this - # site had twice (once a 404 body as the home page, once a dist/ beside the - # Dockerfile). Buildplan already asserts the path mapping; this asserts the - # artifact is actually there. + # An exporter that "succeeds" with an empty dist/ is a failure this + # repository has already had twice - once a 404 body as the home page, + # once a dist/ written beside the Dockerfile. buildplan already asserts + # the path mapping; this asserts the artifact is actually there. run: | test -f docs/site/dist/index.html || { echo "::error::no index.html in the export"; exit 1; } test -f docs/site/dist/404.html || { echo "::error::no 404.html in the export"; exit 1; } From 00b7df06be1ab261562e992d7c6a5103eaa25b4b Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 19:34:45 +0330 Subject: [PATCH 25/29] docs/site: name the 404 template after its method, because V 0.5.2 resolves an explicit path differently The docs workflow builds on **V 0.5.2**, and `$veb.html('404.html')` fails there: docs/site/veb_site.v:297:19: error: veb HTML template "404.html" not found It compiled on master, which is why this was not a local failure: the two compilers resolve a *named* template differently. V 0.5.2 looks for `/404.html` next to the source file (`vlib/v/parser/comptime.v:541`), while master also falls back to the `templates/` directory. My file is at `templates/404.html`, so only one of the two found it. So the name now comes from the function rather than from a string literal: `$veb.html()` with no argument resolves `templates/.html` relative to the file's directory on **both** compilers, and the template moves to `templates/not_found.html`. That is why it stayed a route rather than becoming an inline string - the route is what gives it a URL for the export to GET. Verified on both, with the same output, rather than on the one that was already passing: VMODULES= v -prod -o site052.exe veb_site.v -> OK ./site052.exe --export -> 831 + 693 bytes v -prod -o site.exe veb_site.v -> OK (ef2ec06) ./site.exe --export -> 831 + 693 bytes The difference between those two cells is the whole reason this file compiles where it does, and it is recorded here rather than left to be rediscovered: the docs site is the part of this repository that *can* build on a release, and the constraint that keeps it that way is now measured rather than assumed. --- docs/site/templates/{404.html => not_found.html} | 0 docs/site/veb_site.v | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/site/templates/{404.html => not_found.html} (100%) diff --git a/docs/site/templates/404.html b/docs/site/templates/not_found.html similarity index 100% rename from docs/site/templates/404.html rename to docs/site/templates/not_found.html diff --git a/docs/site/veb_site.v b/docs/site/veb_site.v index fca514c..fdd1eae 100644 --- a/docs/site/veb_site.v +++ b/docs/site/veb_site.v @@ -294,7 +294,7 @@ fn veb_http_get_any(path string) !string { // Fixing the preview status means finding veb's override point, not a line here. @['/404'] fn (mut ctx Context) not_found() veb.Result { - return $veb.html('404.html') + return $veb.html() } // output_path maps a route URL to the file the export writes. The mapping — the From 0c603107a01e336cce80aaf3de88521187d4b81e Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 19:56:31 +0330 Subject: [PATCH 26/29] docs/site: not_found needs `pub`, because veb calls it from another module Same run, next error - and this one was already inside veb: /home/runner/work/_temp/v/vlib/veb/veb.v:640:15: error: method `Context.not_found` is private 640 | user_context.not_found() veb dispatches an unmatched path by calling `user_context.not_found()` from inside `vlib/veb/veb.v`. That is a different module, so the method on `Context` has to be public - V 0.5.2 refuses it outright, while master accepted the missing keyword and compiled. A missing `pub` that one compiler tolerates and the other rejects is how the local build stays green while CI goes red, which is the same shape as the template-path difference in the previous commit. `pub fn (mut ctx Context) not_found()` now, and verified on both compilers rather than only the one that was already passing: VMODULES= v -prod -o a.exe veb_site.v -> OK ; a.exe --export -> 831+693 v -prod -o b.exe veb_site.v -> OK ; b.exe --export -> 831+693 46/46, fmt clean. The pattern across the last two commits is worth naming once, because it is the second time it happened in one workflow: `docs.yml` builds on a RELEASED V while the site is developed against master, and every divergence between them showed up as a red job with nothing in the local run. That is the argument for pinning the toolchain and for testing against the one the workflow actually uses, written here so the next divergence has somewhere to point. --- docs/site/veb_site.v | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/site/veb_site.v b/docs/site/veb_site.v index fdd1eae..ad2be40 100644 --- a/docs/site/veb_site.v +++ b/docs/site/veb_site.v @@ -292,8 +292,13 @@ fn veb_http_get_any(path string) !string { // `/nope` answer 200. GitHub Pages supplies the real 404 status for // `dist/404.html` itself, so the served artifact is correct either way. // Fixing the preview status means finding veb's override point, not a line here. +// `pub` is load-bearing, not decoration. veb calls this as +// `user_context.not_found()` from inside `vlib/veb/veb.v`, which is another +// module, so a private method cannot be reached - V 0.5.2 says so outright: +// `error: method Context.not_found is private`. Master compiled it without the +// modifier, which is exactly how a missing keyword survives a local run. @['/404'] -fn (mut ctx Context) not_found() veb.Result { +pub fn (mut ctx Context) not_found() veb.Result { return $veb.html() } From b22804a58c8570c73daaebe8736b323f827cc202 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 20:06:32 +0330 Subject: [PATCH 27/29] docs.yml: the export runs from docs/site too, or it cannot find the binary the build just made The build step is green now - 1m11s, a real compile on V 0.5.2 with the template and `pub` fixes in. The export step then died with exit 127: ##[group]Run ./site.exe --export ##[error]Process completed with exit code 127 `./site.exe` was written by the previous step, which has `working-directory: docs/site`, and the export step had none - so it looked for the binary at the repository root, where it does not exist. Exit 127 is `command not found`, which reads as "the build produced nothing" and not as "the binary is one directory over". `working-directory: docs/site` on the export as well. The output path is not affected: `buildplan.site_paths` resolves `dist/` from `@FILE`, so the artifact lands in `docs/site/dist/` identically from either directory - which is why the previous step's check passes either way and only the `./site.exe` invocation needs the directory. Also `set -eu` on the artifact check, which was the one `run:` block without it: without `-e`, a failing `test` inside the `||` chain still reports success. --- .github/workflows/docs.yml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 40b4d58..8a727c1 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -127,6 +127,13 @@ jobs: # the `-- --export` argument is not reliably forwarded through `v run`. # The first run that used the combined form sat on a listening server # until the job timed out. + # + # `working-directory` is here for the same reason as the build's: the + # binary is written there, and a previous version of this step ran from + # the repository root and failed with exit 127 (`./site.exe: not found`). + # The export output itself is resolved from `@FILE` via + # `buildplan.site_paths`, so it lands in `docs/site/dist/` either way. + working-directory: docs/site run: ./site.exe --export - name: Fail if the export produced nothing # An exporter that "succeeds" with an empty dist/ is a failure this @@ -134,6 +141,7 @@ jobs: # once a dist/ written beside the Dockerfile. buildplan already asserts # the path mapping; this asserts the artifact is actually there. run: | + set -eu test -f docs/site/dist/index.html || { echo "::error::no index.html in the export"; exit 1; } test -f docs/site/dist/404.html || { echo "::error::no 404.html in the export"; exit 1; } echo "exported $(find docs/site/dist -name '*.html' | wc -l) HTML file(s)" From eaba6e3191f84e3ae9e6430d7c7938165d6695a6 Mon Sep 17 00:00:00 2001 From: metif12 Date: Sun, 11 Oct 2026 20:16:33 +0330 Subject: [PATCH 28/29] CHANGELOG: record the five failures that got docs.yml to its first green run The docs workflow passes: build 8/8 steps green including upload-pages-artifact, deploy skipped by design on a pull request. The cascade is worth the entry it takes, because four of the five causes were invisible locally and one of them was a real bug in this repository twice over. `oven-sh/setup-v` no longer exists. `vlang/setup-v@v1.7` cannot install V as a prebuilt at all - `downloadPrebuilt` was added after that tag, so it compiles V forever, and that build cannot succeed because the bootstrap compiler rejects 0.5.2's syntax. `GITHUB_PATH` does not affect the running step. The export step could not find the binary the build step had just made, because only one of them set working-directory. And the two interesting ones are both about the same thing: docs.yml builds on a released V while the site is developed against master. `$veb.html('404.html')` resolves differently on the two compilers, and `not_found` needed `pub` because veb calls it from another module - which master tolerated and 0.5.2 refuses. Both are fixed and verified against both compilers via VMODULES, not against the one that was already passing. Windows remains red at the same pre-existing step 4 as main, unchanged. --- CHANGELOG.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bb7297..f9f6615 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -399,6 +399,51 @@ both halves of that so the next person does not have to guess which is which. ### Fixed +- **The docs workflow is green for the first time, and the path there was five + failures that were each invisible locally.** `docs.yml` now builds, exports, + verifies and uploads the artifact on a released V. The cascade, because the + order is the lesson: + + 1. `oven-sh/setup-v@v2` — **the repository no longer exists**. Died at step 1 + with `Unable to resolve action oven-sh/setup-v, repository not found`. + 2. `vlang/setup-v@v1.7` with `version: v0.5.2` — the tag looked right (both + `0.5.2` and `v0.5.2` are real refs, checked) and still resolved to a **source** + download plus `make`, which cannot succeed here: the bootstrap compiler is + newer than 0.5.2 and master has stopped accepting 0.5.2's parenthesised-`if` + syntax (`vlib/math/bits/bits.v:621`). + 3. `vlang/setup-v@v1.7` with `version: 0.5.2` — still a source build, and the + reason is in the action's own history: **`downloadPrebuilt` was added after + tag v1.7** (`git grep downloadPrebuilt v1.7` returns nothing while HEAD has + it), so this action compiles V on every version, forever. So there was no + setup-v that fixed it, and the action was **removed** rather than + reconfigured. + 4. `GITHUB_PATH` — the download, the checksum and the unzip all succeeded, and + the step still died with `v: command not found`, because writing + `$GITHUB_PATH` changes the PATH of *subsequent* steps, not the running one. + 5. The export step — exit 127, because the build step had + `working-directory: docs/site` and the export did not, so `./site.exe` was + looked for in the repository root. + + V is now installed as the **release asset V publishes**, pinned by SHA-256, + which also takes a third-party action out of the toolchain entirely. + + Three of those five were real bugs in this repository, and both of the + interesting ones came from the same root: **`docs.yml` builds on a *released* V + while the site is developed against master**, and every divergence between them + showed up as a red job with nothing in the local run. `$veb.html('404.html')` + resolves differently on the two compilers (0.5.2 looks for + `/404.html`, master also falls back to `templates/`), and `not_found` + needed `pub` because veb calls it from another module — which master tolerated + and 0.5.2 refuses. Both are fixed, and **verified on both compilers** by + building with `VMODULES` pointed at each one's veb rather than only the one that + was already passing, which is the habit worth taking from this cycle. + + Final state: `build` passes 8/8 steps including `upload-pages-artifact`; `deploy` + is skipped by design on a `pull_request` (it deploys on push to `main`, which + needs Pages enabled). The `windows` job remains red at the pre-existing step 4 + "This compiler can build this repo", unchanged from `main`. + + - **`docs.yml` was red before it ever reached the site, and the cause was a dependency this repository cannot see.** `oven-sh/setup-v` no longer exists; the job failed at step 1 ("Set up job") with From 06c0beb4bae4d2cdbd0c0cdbf558a8d0fc91105e Mon Sep 17 00:00:00 2001 From: metif12 Date: Tue, 13 Oct 2026 11:54:28 +0330 Subject: [PATCH 29/29] CI: the Windows job builds V from source at the pinned commit, ending its red state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Windows job was red since the first run that could see it, and the cause was never the repository. It installed V **0.5.2 from the release zip**, and that V's vlib has no `json2` — `bridge/` and `state/` import it, so `v test .` could not compile. The smoke step that existed precisely to name that failure was doing its job on a machine nobody had run it on; what was missing was the fix. There is no release that has `json2`, so there was no version bump to make: `json2` was added to vlang/v on 2026-10-03, after every published tag. Verified against the API rather than assumed — `gh api repos/vlang/v/contents/vlib/json2 ?ref=7647ce1` returns 404. My first check of this was wrong and reported the opposite, because a 404 error object is still truthy through `ConvertFrom-Json`; the corrected check is what the commit message relies on. So the job now builds V from source, which is what AGENTS.md/ROADMAP already named as the only correct pin: 1. **MSYS2 ucrt64 first, and `ucrt64\bin` on PATH** — moved above the V build, because `makev.bat -gcc` needs a working `cc1`, and a cc1 that cannot load its own DLLs fails as a silent gcc error rather than as a missing symbol. 2. **V at the same pinned commit the Dockerfile builds** (`60542b9`), so the two CI platforms compile against one compiler instead of two that happen to agree. Fetched by full SHA: a shallow clone's HEAD is not that commit. 3. **`makev.bat -gcc`, then `v symlink`** — V's own Windows build recipe, the first thing `vlang/v`'s `windows_ci_gcc.yml` runs after checkout, rather than one invented here. The `-ldflags` / `-cflags` stay, and the comment now says why they stay: they are **version-scoped**, needed on 0.5.2 and unnecessary on the master now pinned. A command that works on both compilers beats one that is minimal on whichever we pin this month, and `buildplan.cli_flags` emits them for the same reason with a test asserting them on purpose. Removing the flags would mean removing that assertion, which turns a version difference back into a mystery. The `json2` smoke step is kept — it is now the cheapest possible proof that the pinned commit is the one the job thinks it is. `workflow_test.v` guards `ci.yml` and is green (7/7 buildplan), `v fmt -verify` clean. **What is not claimed:** no Windows run has gone green yet. The failure mode is ended by construction, but a red-to-green transition on a runner nobody has seen green is a fact only the runner reports, so ROADMAP and README say the change was made and leave the outcome to the run. --- .github/workflows/ci.yml | 179 ++++++++++++++++++++++++--------------- README.md | 14 +-- ROADMAP.md | 66 ++++++++++----- 3 files changed, 165 insertions(+), 94 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 21e6d1c..9293fb4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -74,97 +74,142 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Install V - # THE PINNED RELEASE ZIP, NOT winget. `winget install --id=VLang.V` - # fails with "No package found matching input criteria" - there is no - # such package in the winget source (measured 2026-10-05, and reproduced - # against the runner's own `winget search VLang`, which returns nothing). + - name: Install MSYS2 ucrt64 + the webview packages + # MOVED TO THE TOP, and that move is the whole fix for this job's + # long-standing red state. # - # Downloading the release is better than winget would have been anyway, - # for a reason that is not about winget: it PINS the compiler. Every - # other flag in this job is justified against a specific V - the - # `-ldflags "-lws2_32"` below is needed on 0.5.2 and unnecessary on - # master - so "whatever winget had this morning" made those comments - # untrue by construction. 0.5.2 is pinned to match them. + # It used to sit after `Install V`, because V was installed as the + # 0.5.2 release zip and that zip needs no C compiler to unpack. But + # 0.5.2 has no `json2` in its vlib - `json2` was added to vlang/v on + # 2026-10-03, which is after every published tag - so `bridge/` and + # `state/` could not compile, and the smoke step below failed with + # `no vlib\json2`. AGENTS.md 1b named the only fix that works: build V + # from source at a pinned commit, with MSYS2 installed BEFORE it + # because V's own Windows build needs a C compiler. # - # It also does not depend on MSYS2, which the next step installs, and - # that constraint is unchanged from the winget version: V's own `make` - # on Windows is not what this job is here to test. + # So the order is now the one that constraint forces: toolchain first, + # compiler second. The same pinned commit the Dockerfile builds, so + # the two CI platforms compile against the same V rather than against + # two different ones that happen to agree. run: | - $ver = '0.5.2' - $zip = Join-Path $env:RUNNER_TEMP 'v_windows.zip' - $dest = Join-Path $env:RUNNER_TEMP 'vlang' - Invoke-WebRequest -Uri "https://github.com/vlang/v/releases/download/$ver/v_windows.zip" -OutFile $zip - Expand-Archive -Path $zip -DestinationPath $dest -Force - # The archive contains a top-level `v/` directory, so v.exe and vlib/ - # end up as SIBLINGS inside it: $dest\v\v.exe and $dest\v\vlib\. - # Putting $dest\v on PATH is therefore what makes `v` resolve. - $vbin = Join-Path $dest 'v' - "$vbin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append + choco install msys2 -y --no-progress + C:\msys64\usr\bin\bash -lc "pacman -Sy --noconfirm --needed mingw-w64-ucrt-x86_64-webview mingw-w64-ucrt-x86_64-webview2-loader" + + - name: Put ucrt64 on PATH + # Before the V build, not just before the tests. ADR-0005's rule is + # about EVERY later step: without `C:\msys64\ucrt64\bin` on PATH even + # `cc1` cannot find its own DLLs, which fails as a SILENT gcc failure + # rather than a missing-symbol error - and a V built by a cc1 that + # could not load is a V that fails later for a reason nobody can see. + # GITHUB_PATH only affects subsequent steps, which is exactly the + # scope wanted. + # + # SINGLE quotes, and they are load-bearing. A YAML double-quoted scalar + # processes backslash escapes, and `\m` is not one - so the double-quoted + # form of this line was not valid YAML at all. GitHub rejects the whole + # file, reports "This run likely failed because of a workflow file issue", + # and runs zero jobs in 0s. That is the second, distinct cause of the same + # symptom `buildplan/workflow_test.v` was written for: it caught the + # indentation break, and it cannot catch this, because a line-prefix check + # cannot see inside a scalar. + run: | + 'C:\msys64\ucrt64\bin' | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append + + - name: Build V from source at the pinned commit + # THE PIN, and why it is a commit rather than a tag. + # + # A tag cannot work: no published release contains `json2`. vlang/v + # added it on 2026-10-3, every release predates that, and + # `bridge/` + `state/` import it - so `v test .` fails with + # `builder error: cannot import module "json2" (not found)`. Measured + # against the API's own answer rather than assumed: `gh api + # repos/vlang/v/contents/vlib/json2?ref=7647ce1` returns 404, while + # the same query at the pinned commit returns the module. + # + # The commit is the SAME one the Dockerfile builds, so the Linux and + # Windows jobs compile this repository against one compiler rather + # than two. Bump it in both places together. + # + # `makev.bat -gcc` is V's own Windows build command - it is the first + # thing `vlang/v`'s `windows_ci_gcc.yml` runs after checkout, so this + # is the recipe V itself validates on a runner rather than one invented + # here. The fetch-by-SHA form is used because a shallow clone's HEAD is + # not the pinned commit, and GitHub serves any reachable commit that + # way. + # + # `v symlink` is V's own next step and is kept: `v` resolves its own + # vlib relative to the executable, and this is the binary that step + # leaves on PATH. + run: | + $sha = '60542b9904a3a0102575ec1104e548996f650a83' + $src = Join-Path $env:RUNNER_TEMP 'vsrc' + if (Test-Path $src) { Remove-Item $src -Recurse -Force } + git init -q $src + git -C $src remote add origin https://github.com/vlang/v.git + git -C $src fetch --depth 1 origin $sha + if ($LASTEXITCODE -ne 0) { throw "could not fetch V at $sha" } + git -C $src checkout -q FETCH_HEAD + Push-Location $src + .\makev.bat -gcc + if ($LASTEXITCODE -ne 0) { throw "makev.bat failed with exit code $LASTEXITCODE" } + .\v.exe version + .\v.exe symlink + if ($LASTEXITCODE -ne 0) { throw "v symlink failed with exit code $LASTEXITCODE" } + Pop-Location + "$src" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append - name: This compiler can build this repo # A smoke step, and it exists because of a measured failure mode rather # than a hypothetical one: `bridge/` and `state/` import `json2`, and a V # install whose vlib has no `json2` fails with # builder error: cannot import module "json2" (not found) - # which reads like a missing dependency in this repo and is not one. On - # 2026-10-03 BOTH V installs on the machine that could have built it were - # affected in one way or another (one lacked json2, the other needed - # -enable-globals). A version check here turns "CI is red for a reason - # nobody can see" into one line of output. + # which reads like a missing dependency in this repo and is not one. + # + # This step is what turned that into a readable failure while the job + # was pinned to 0.5.2, and it is kept now that the job builds from + # source - a green line here is the cheapest possible proof that the + # pinned commit is the one the job thinks it is. # # ONE Split-Path, not two, and the reason is the layout: v.exe sits in - # the same directory as vlib/ (the step above puts $dest\v on PATH), so - # one level up from v.exe IS the vroot. The previous two-level form was - # only correct for a layout where v.exe lives in a bin/ beside vlib/, and - # it happened to pass on the machine this was written on purely because - # that machine's `v` is a .bin\v.bat forwarder - which is exactly the - # kind of coincidence that stops being true on a fresh runner. + # the same directory as vlib/ (the step above puts the source root on + # PATH), so one level up from v.exe IS the vroot. The previous two-level + # form was only correct for a layout where v.exe lives in a bin/ beside + # vlib/, and it happened to pass on the machine this was written on + # purely because that machine's `v` is a .bin\v.bat forwarder - which is + # exactly the kind of coincidence that stops being true on a fresh + # runner. run: | v version $vroot = Split-Path (Get-Command v).Source if (-not (Test-Path (Join-Path $vroot 'vlib\json2'))) { - Write-Error "no vlib\json2 under $vroot - bridge/ and state/ import json2, so this V cannot build this repo. Pinned V version is 0.5.2; a newer V has it (see AGENTS.md 1b)" + Write-Error "no vlib\json2 under $vroot - bridge/ and state/ import json2, so this V cannot build this repo. The pinned commit should have it (see AGENTS.md 1b)" exit 1 } Write-Output "json2 present under $vroot" - - name: Install MSYS2 ucrt64 + the webview packages - run: | - choco install msys2 -y --no-progress - C:\msys64\usr\bin\bash -lc "pacman -Sy --noconfirm --needed mingw-w64-ucrt-x86_64-webview mingw-w64-ucrt-x86_64-webview2-loader" - - - name: Put ucrt64 on PATH - # A separate step, and after the install, because ADR-0005's rule - # is about EVERY later step: without C:\msys64\ucrt64\bin on PATH - # even `cc1` cannot find its own DLLs, which fails as a SILENT gcc - # failure rather than a missing-symbol error. GITHUB_PATH only - # affects subsequent steps, which is exactly the scope wanted. - # SINGLE quotes, and they are load-bearing. A YAML double-quoted scalar - # processes backslash escapes, and `\m` is not one - so the double-quoted - # form of this line was not valid YAML at all. GitHub rejects the whole - # file, reports "This run likely failed because of a workflow file issue", - # and runs zero jobs in 0s. That is the second, distinct cause of the same - # symptom `buildplan/workflow_test.v` was written for: it caught the - # indentation break, and it cannot catch this, because a line-prefix check - # cannot see inside a scalar. - run: | - 'C:\msys64\ucrt64\bin' | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append - - name: v test . - # The `-ldflags` is not optional **on V 0.5.2**, which is what the winget - # step above installs, and the reason is a V bug rather than a repo one: - # V 0.5.2's `dependency_scan_fallback` link path emits `#flag`-sourced - # `-l` flags BEFORE most object files, and GNU ld only resolves an archive - # against the objects that precede it, so `net.http`'s `ws2_32` never - # resolves. It has to arrive as `-ldflags`, which is emitted last. + # The `-ldflags` is kept, and the reason it is kept is that it is + # VERSION-SCOPED rather than needed here. On V 0.5.2 it was not + # optional, because of a V bug rather than a repo one: 0.5.2's + # `dependency_scan_fallback` link path emits `#flag`-sourced `-l` flags + # BEFORE most object files, and GNU ld only resolves an archive against + # the objects that precede it, so `net.http`'s `ws2_32` never resolves. + # It has to arrive as `-ldflags`, which is emitted last. # - # It is also unnecessary on a newer V, measured 2026-10-03 across 33 test - # files on V master — so the flag is here because of the compiler this job - # pins, not because the repo needs it. See AGENTS.md 1 and 1b. + # It is unnecessary on a newer V, measured 2026-10-03 across 33 test + # files on V master - and this job now pins master, so the flag is not + # doing any work. It stays because a command that works on both + # compilers is worth more than one that is minimal on the compiler we + # happen to pin this month: `buildplan.cli_flags` still emits it for + # exactly that reason, and the test that asserts it is what documents + # that it exists on purpose. Removing it means also removing the + # assertion, which turns a version difference into a mystery again. run: v -cc gcc -ldflags "-lws2_32" test . - name: build the CLI + # The `-cflags` on this step is the same story as the `-ldflags` above: + # needed on 0.5.2, unnecessary on the master this job pins, kept so one + # command serves both and `buildplan.cli_flags` stays truthful. run: v -cc gcc -cflags "-Wno-incompatible-pointer-types" -ldflags "-lws2_32" -o vails.exe ./cli - name: vails build produces a RUNNABLE binary diff --git a/README.md b/README.md index c25d561..1f1fbc1 100644 --- a/README.md +++ b/README.md @@ -246,12 +246,14 @@ native runner with MSYS2 ucrt64. The Windows job's distinguishing step runs directory** — a green CI that ships an `.exe` which cannot start is worse than no CI. A `v*` tag additionally triggers a version-stamped release build. -The two jobs are not equally green and it is worth knowing which is which: the -**Linux job passes**, and the **Windows job still fails** at the step that checks -whether the runner's own V can build this repository at all — it installs a -*released* V, and no release contains `json2`, which `bridge/` and `state/` -import. That is a toolchain gap, not a regression, and the Dockerfile's pin is -why the Linux side is not affected by it. +Both jobs build V from source at the same pinned commit (the Linux side in the +Dockerfile, the Windows side with `makev.bat -gcc`), so they compile this +repository against one compiler rather than two. **The Linux job passes.** The +Windows job used to fail before it built anything, because it installed a +*released* V and no release contains `json2`, which `bridge/` and `state/` +import — a toolchain gap rather than a regression. That is fixed by the pin; +whether the Windows job is green end to end is a fact only its own runner can +report, and `ROADMAP.md` records it either way. ```sh docker build -t vails-ci -f Dockerfile . diff --git a/ROADMAP.md b/ROADMAP.md index 0968cca..3712b24 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -113,18 +113,38 @@ array") and it exists **only on `master`**. Checked and confirmed: not in tag it. It lives at `vlib/json2`, not `vlib/v/json2`, which is why a `vlib/v` listing looks like it is missing. -So the Windows job **cannot** be pinned to a release, which is the opposite of -what pinning was supposed to buy, and it means the `-ldflags "-lws2_32"` comment -in `ci.yml` is describing a version that cannot get as far as needing it. The -only correct pin is a **vlang/v commit**, which means building V from source on -the runner — the same thing the Linux container already does successfully. That -is a real restructure of the windows job (MSYS2 has to be installed *before* V, -because V's own Windows build needs a C compiler), and it is not done. - -What is true right now, precisely: **CI runs jobs; the Windows job installs a -compiler that provably cannot build this repo, and says so in one named line -instead of failing obscurely two steps later.** That is the smoke step working -as designed, on a machine nobody had ever run it on. +So the Windows job **could not** be pinned to a release, which is the opposite of +what pinning was supposed to buy, and it meant the `-ldflags "-lws2_32"` comment +in `ci.yml` was describing a version that could not get as far as needing it. The +only correct pin was a **vlang/v commit**, which means building V from source on +the runner — the same thing the Linux container already does successfully — and +that required a real restructure of the windows job, because MSYS2 has to be +installed *before* V (V's own Windows build needs a C compiler). + +**That restructure is done, on 2026-10-11.** The windows job now: + +1. installs MSYS2 ucrt64 **first**, and puts `ucrt64\bin` on PATH, because + `makev.bat -gcc` needs a working `cc1` and a cc1 that cannot load its own DLLs + fails as a silent gcc error rather than as a missing symbol; +2. fetches V at the **same pinned commit the Dockerfile builds** + (`60542b9904a3a0102575ec1104e548996f650a83`), so the two CI platforms compile + this repository against one compiler instead of two that merely happen to + agree; +3. builds it with `makev.bat -gcc` — V's own Windows build command, the first + thing `vlang/v`'s `windows_ci_gcc.yml` runs after checkout, so it is the + recipe V validates on a runner rather than one invented here. + +The `-ldflags` and `-cflags` stay in the job, and they stay for a reason that +survived the restructure: they are **version-scoped**, needed on 0.5.2 and +unnecessary on the master now pinned, and a command that works on both compilers +is worth more than one that is minimal on whichever we happen to pin this month. +`buildplan.cli_flags` still emits them for exactly that reason, and the test +asserting them is what documents that they exist on purpose. + +What is true right now, precisely: **both jobs build against a pinned V-from-source +compiler, and the Windows smoke step that used to fail on a release V now checks +the pinned commit it is actually testing against.** The `json2` check is kept as +the cheapest possible proof that the pin is the one the job thinks it is. **And the Linux backlog that became visible is now closed: 44 of 44 green.** It began as 20 failing files, which is not a list of flaky tests but three distinct @@ -191,15 +211,19 @@ code in this repo should read §2c before it is written. The repo's own rule (AGENTS.md §5) is that a line either names a proof or says it is unproven. The four things most likely to be over-read: -- **B2+B3 (Dockerfile + CI): the Linux job is green and the Windows one is not, - and neither of those is the same as "CI is green".** The "never executed" claim - was true until 2026-10-03. Since then the Linux container job has **passed - repeatedly** (5m36s on the branch in #1, after starting at 20 of 44 test files - failing); the Windows job **still fails**, at the step that checks whether the - runner's own V can build this repository at all — it installs a *released* V, - and no release has `json2`. So the accurate statement is "one of the two jobs is - green", and the more useful one is "the Linux suite is now proven on a clean - runner", which is something this file could not say before. +- **B2+B3 (Dockerfile + CI): both jobs now build against a pinned V-from-source + compiler, which is as far as this file can claim without a green Windows run.** + The "never executed" claim was true until 2026-10-03. Since then the Linux + container job has **passed repeatedly**; the Windows job used to fail at the step + that checks whether the runner's own V can build this repository at all, because + it installed a *released* V and no release has `json2`. As of 2026-10-11 the + Windows job builds V from source at the same pinned commit the Dockerfile uses, + so that failure mode is gone by construction. **What is still unproven is the + run itself** — a red-to-green transition on a runner nobody has seen green is a + claim only the runner can settle, and this file will say which way it went when + it does. The accurate sentence today is: "both jobs compile against the same + pinned V, and the Linux half has been proven green on a clean runner many + times." - **The Linux GUI proofs need a real session, and three of the screenshots this file used to cite have never existed.** `git log --all` returns **zero commits** for `tests/e2e_windows/tray.png`, `tests/e2e_windows/menu.png` and