Repository navigation
Linux suite green, menu.set_menu stops swallowing hook failures, and a guard for a json2 bug that silently broke the CLI - #1
Conversation
…iling 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.
…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.
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".
…aiming 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.
…a caller outside its own file
…est 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.
…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.
CI status, and which red is pre-existingBoth platforms were red on the base commit. Comparing the two runs so a reviewer
Run 37279867224 is the base commit's run; run 37309758751 is this branch. The Linux red was mine to fix, and it is fixedIt failed at The Windows red is pre-existing and not caused by this branchIt fails at step 4, "This compiler can build this repo" — and it fails there
So it is a toolchain gap, not a regression: the runner installs a released V, and I have not touched CI. Fixing it means building V from a pinned commit on the If you want the local equivalent of what Linux CI proveddocker build -t vails-ci -f Dockerfile . && docker run --rm -e VFLAGS="-gc none" vails-ci45/45 here, on the same container image CI uses. |
…eproduction 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.
Correction: I checked my own reproduction and it did not reproducePushing a commit rather than editing history, because the mistake is worth I filed an upstream bug report with a minimal reproduction that does not
The trigger is two conditions together: the module declaring the decoded type The evidence that pins it, each row a separate binary:
The reproduction in the report also had a structural error: it put What did not changeThe symptom in this repository was never in doubt.
On the compiler versionFair question, and the answer is not ideal. Everything here was measured on V The upstream report says exactly that and asks for re-confirmation rather than Also unverifiable by anyone: no released V has One lead on the cause, flagged as a hypothesisBoth builds emit the same statement: config__Cfg result = (config__Cfg){.name = _str_36};but |
…ted 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.
…he .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.
The compiler moved, the bug is gone, and two of my explanations died with itTwo commits since the last comment, both finishing audit items. The short version Verified, not inferred: the same reproduction across three fresh project roots A V maintainer had already closed [vlang/v#29508] as Two explanations I had written down, both now killedBoth were in
|
| job | on main |
on this branch |
|---|---|---|
| linux (container) | ❌ red at v test . |
✅ pass, 5m36s |
| windows (msys2) | ❌ red | ❌ same step 4 |
Windows is unchanged from main: it fails at step 4, "This compiler can build
this repo", and steps 5–10 are skipped. That step is the guard which detects the
condition in AGENTS.md §1b — the runner installs a released V, and no release
has json2 at all. CI is not touched by this branch; fixing it means building V
from a pinned commit on the runner, which is a separate piece of work and is called
out as not done rather than half-done.
45/45 locally on Windows and in the container, v fmt -verify clean, encoding
clean (no BOM, no null bytes, no U+FFFD, final newline on every touched file).
One thing worth flagging to whoever merges
The CLI works because V moved, not because we fixed anything. If the compiler
regresses, or a new module imports net.http, the guard is what makes it visible
at review time now. And the reasoning that json2 fixed it is not bisected, so
AGENTS.md §1b says explicitly not to attribute it.
…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.
…he 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.
…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.
…he 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.
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.
…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.
… 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.
…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.
…d 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.
…ndency 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.
…alls 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.
…-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.
…uccessful 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.
…tes 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.
…solves 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 `<dir>/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/<fn-name>.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 0.5.2's vlib> 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.
…odule
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 0.5.2 veb> 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.
…inary 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.
…een 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.
… its red state 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.
What this is
Seven commits from one session's worth of work: the Linux test backlog, four
small correctness/refactor items the audit found, a documentation accuracy pass,
and a new guard for a compiler bug that broke a shipped command silently.
Nothing here changes the public API except one behaviour change that was a bug.
Measured, before and after
v -cc gcc test .on Windowsv test .on Linux (CI container,-gc none)v fmt -verify .The Linux suite had never been run in this repository. The first run had 20 of
44 files failing for three unrelated root causes; all three are in the first
commit.
The commits, in order of interest
1. Linux green (20 of 44 → 44/44).
services/drop.vnamed a Windows-onlyfunction from platform-neutral code;
webview_linux.c.vhad 7 compile errorsleft by the multi-window work;
jobs_test.vasserted a Windows-only error string;buildplan.app_flagshad a$if windowswhose branches were identical.2.
menu.set_menunow fails instead of pretending it worked.attach_bar_hookcaught thewebview.attacherror,eprintln'd it and returnednormally — so the command resolved
okon a window whose bar was attached withnothing listening. The comment above the
eprintlnclaimed the opposite.trayand
droppropagated the identical failure from the identical call.3.
dtsmarks the blocking commands in the generated.d.ts. The fourcommands that open a native dialog now say so in JSDoc, with the set pinned so a
fifth one shipped without a marker fails the suite.
4. A refactor that had to be reverted, and why that is in the history.
Collapsing tray/menu/drop's three nil guards into
webview.detachcrashed thesuite. V 0.5.2 faults on passing a nil variable to a
mut &Tparameter, beforethe body runs — so a nil check in the callee is unreachable in the only way callers
call it.
detach's doc comment now says so and points atAGENTS.md§2c, so thenext person does not retry it. The genuine part of the cleanup (capture rule
stated once, field cleared before detaching) stayed.
5.
toast_availablemade private — nopub fnremains in any.c.v.6. Documentation accuracy. Three documents cited screenshots that have never
existed here (
git log --allreturns zero commits for all three). Dated ADRs goterrata appended, not rewritten. Two stale claims were also recorded as history
rather than deleted — see below.
7. The new guard, described next.
The one thing worth reading the diff for
buildplan/json2_import_test.v.On V master,
json2.decode[T]returns a zero-valued struct with no error whennet.httpis linked into the binary and the decode is instantiated in a moduleother than the one importing
net.http.devis this repo's onlynet.httpimporter and
cliis the only module linking it toconfig, sovails doctor,run,buildanddtsall report a validvails.jsonas "name must not beempty".
v test .was 44/44 green the whole time, because each_test.vis its ownbinary and no test file imports both
devandconfig— the failingcombination was never assembled.
The guard asserts the precondition rather than the bug: a test that reproduces
it would only pass while the compiler is broken, and would go red on the fix. So
it pins that
net.httphas exactly one importer, that this importer and everyjson2.decodeinstantiator stay disjoint, and thatcliis still where the twomeet. Seen red by planting an
import net.httpintoconfig.v— three assertionsfailed, naming file and line — then reverted.
This does not fix the CLI. The bug is in the compiler; the guard stops the
exposure from being widened without anyone noticing, and
ROADMAP.mdcarries itas a build blocker. Upstream report is going to
vlang/vseparately.Corrections to claims that were already in the repository
Two were stale, and both understated what this project achieves:
ROADMAP.mdsaidv test webviewon Windows "cannot be run: it takes the hostdown" (measured 4× on 2026-09-30, again 2026-10-03). 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 — so the row keeps the history and says
currently green, not fixed.
README.mdsaid the Windows test command "carries one extra flag, and it is notoptional", above a code block with no extra flag in it. No link flag has been
needed since the move to the V master build this project requires. The reason
is kept so the flag reads as version-scoped rather than mysterious.
Reviewer notes
buildplan_test.vchange asserts the whole flag stringrather than one flag, because the defect was an extra flag no per-flag
assertion could see.
menu_test.v's first new test is wrapped in a Windows-only compile-timebranch:
attach_bar_hooklives inmenu_windows.c.v. An earlier version of itscomment claimed the guard was cross-platform because
webview.attachis — thatversion did not compile on Linux. The cross-platform half is asserted through
set_menu, which both backends gate on the window first.examples/*/frontend/vails.d.tsfilesstill lack the new blocking-command JSDoc, because
vails dtscannot readvails.jsonwhile the compiler bug stands. Their headers say "do not edit", sothey are left alone and the gap is recorded in
CHANGELOG.mdunder "Not done".Reviewer checklist
docker build -t vails-ci -f Dockerfile . && docker run --rm -e VFLAGS="-gc none" vails-ci→ 45/45$env:PATH = "C:\msys64\ucrt64\bin;" + $env:PATH; v -cc gcc test .→ 45/45v -cc gcc -o vails.exe ./clibuilds (3 pre-existingos.executedeprecation warnings)vails doctorstill reportsvails.json : INVALID— expected, see above🤖 Generated with Claude Code