Skip to content

Linux suite green, menu.set_menu stops swallowing hook failures, and a guard for a json2 bug that silently broke the CLI - #1

Merged
metif12 merged 29 commits into
mainfrom
fix/linux-suite-and-json2-cross-module-guard
Oct 13, 2026
Merged

metif12 merged 29 commits into
mainfrom
fix/linux-suite-and-json2-cross-module-guard

Conversation

@metif12

@metif12 metif12 commented Oct 5, 2026

Copy link
Copy Markdown
Owner

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

before after
v -cc gcc test . on Windows 20 of 44 failing (never run) 45/45
v test . on Linux (CI container, -gc none) 20 of 44 failing (never run) 45/45
v fmt -verify . — clean
encoding sweep (null / BOM / U+FFFD / final newline) — clean

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.v named a Windows-only
function from platform-neutral code; webview_linux.c.v had 7 compile errors
left by the multi-window work; jobs_test.v asserted a Windows-only error string;
buildplan.app_flags had a $if windows whose branches were identical.

2. menu.set_menu now fails instead of pretending it worked.
attach_bar_hook caught the webview.attach error, eprintln'd it and returned
normally — so the command resolved ok on a window whose bar was attached with
nothing listening. The comment above the eprintln claimed the opposite. tray
and drop propagated the identical failure from the identical call.

3. dts marks the blocking commands in the generated .d.ts. The four
commands 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.detach crashed the
suite. V 0.5.2 faults on passing a nil variable to a mut &T parameter, before
the 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 at AGENTS.md §2c, so the
next person does not retry it. The genuine part of the cleanup (capture rule
stated once, field cleared before detaching) stayed.

5. toast_available made private — no pub fn remains in any .c.v.

6. Documentation accuracy. Three documents cited screenshots that have never
existed here (git log --all returns zero commits for all three). Dated ADRs got
errata 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 when
net.http is linked into the binary and the decode is instantiated in a module
other than the one importing net.http. dev is this repo's only net.http
importer and cli is the only module linking it to config, so vails doctor,
run, build and dts all report a valid vails.json as "name must not be
empty"
.

v test . was 44/44 green the whole time, because each _test.v is its own
binary and no test file imports both dev and config — the failing
combination 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.http has exactly one importer, that this importer and every
json2.decode instantiator stay disjoint, and that cli is still where the two
meet. Seen red by planting an import net.http into config.v — three assertions
failed, 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.md carries it
as a build blocker. Upstream report is going to vlang/v separately.

Corrections to claims that were already in the repository

Two were stale, and both understated what this project achieves:

  • ROADMAP.md said v test webview on Windows "cannot be run: it takes the host
    down" (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.md said the Windows test command "carries one extra flag, and it is not
    optional", 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

  • Commits are single-theme and each is independently revertable.
  • The first commit's buildplan_test.v change asserts the whole flag string
    rather 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-time
    branch: attach_bar_hook lives in menu_windows.c.v. An earlier version of its
    comment claimed the guard was cross-platform because webview.attach is — that
    version did not compile on Linux. The cross-platform half is asserted through
    set_menu, which both backends gate on the window first.
  • Not included: the three checked-in examples/*/frontend/vails.d.ts files
    still lack the new blocking-command JSDoc, because vails dts cannot read
    vails.json while the compiler bug stands. Their headers say "do not edit", so
    they are left alone and the gap is recorded in CHANGELOG.md under "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/45
  • v -cc gcc -o vails.exe ./cli builds (3 pre-existing os.execute deprecation warnings)
  • vails doctor still reports vails.json : INVALID — expected, see above

🤖 Generated with Claude Code

…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.
…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.
@metif12

metif12 commented Oct 5, 2026

Copy link
Copy Markdown
Owner Author

CI status, and which red is pre-existing

Both platforms were red on the base commit. Comparing the two runs so a reviewer
does not have to take the red on trust:

job on main (base 9ab8877) on this branch
linux (container) ❌ failed at step 4, v test . ✅ pass, 5m45s
windows (msys2 ucrt64) ❌ failed at step 4 ❌ same step 4

Run 37279867224 is the base commit's run; run 37309758751 is this branch.

The Linux red was mine to fix, and it is fixed

It failed at v test . — the 20-of-44 backlog that commit 1 addresses. The
container job now runs the full suite green.

The Windows red is pre-existing and not caused by this branch

It fails at step 4, "This compiler can build this repo" — and it fails there
on main too, with steps 5–10 skipped. That step is the guard which detects the
condition documented in AGENTS.md §1b:

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.

So it is a toolchain gap, not a regression: the runner installs a released V, and
no released V has json2 at all (bridge/ and state/ import it), so the guard
refuses to let the job pretend to have tested anything.

I have not touched CI. 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 here.

If you want the local equivalent of what Linux CI proved

docker build -t vails-ci -f Dockerfile . && docker run --rm -e VFLAGS="-gc none" vails-ci

45/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.
@metif12

metif12 commented Oct 5, 2026

Copy link
Copy Markdown
Owner Author

Correction: I checked my own reproduction and it did not reproduce

Pushing a commit rather than editing history, because the mistake is worth
leaving visible — it is the same failure mode as the docs commit before it.

I filed an upstream bug report with a minimal reproduction that does not
reproduce.
I built it as written and it printed the correct value. The bug was
real; the report's trigger claim was a generalization from a case I had not
isolated. Two claims are withdrawn:

claim status refuted by
"json2 + net.http is the broken combination" ✗ a 2-field struct decodes fine with net.http linked
"the trigger is a cross-module decode" ✗ the same 2-field struct in a module named other decodes fine

The trigger is two conditions together: the module declaring the decoded type
is named config, and net.http is linked into the binary. Nothing
about struct shape, nothing about cross-module-ness in general.

The evidence that pins it, each row a separate binary:

module declaring Cfg with net.http
config yes ZERO, no error
config no works
other / conf / configx / xconfig / mymod yes works
config time or sync instead of net.http works

conf, configx and xconfig all work, so it is the exact identifier rather
than a prefix rule. Verified 6/6 on the failing program — deterministic, no
error, exit 0.

The reproduction in the report also had a structural error: it put other.v as a
sibling of main.v, which does not resolve. A module is a subdirectory when a
v.mod is present — the second thing the first attempt got wrong.

What did not change

The symptom in this repository was never in doubt. vails doctor reporting
a valid vails.json as invalid is this bug, and this repo satisfies all three
conditions by construction: the config module is named config, dev imports
net.http, cli links them. Suite 45/45 on Windows and in the Linux container,
fmt clean, encoding clean.

buildplan/json2_import_test.v needed no change to its assertions — it asserts
net.http keeps exactly one importer, that importer and the json2.decode
instantiators stay disjoint, and cli is where the two meet. That invariant
holds under the corrected trigger and is still what stops the combination being
widened unnoticed. Only its header comment changed, to name the real trigger and
to record both withdrawn claims.

On the compiler version

Fair question, and the answer is not ideal. Everything here was measured on V
master bb0d229, which is the compiler built on this machine. Master has since
moved to 3c5f448.
None of the five intervening commits touch vlib/json2 —
but d59952b changes vlib/v/driver/driver.v, vlib/v/markused/markused.v and
ssa/builder.v ("restore module cache hits"), which is a plausible indirect
path, so I cannot claim the bug survives on current master.

The upstream report says exactly that and asks for re-confirmation rather than
asserting current-master breakage. Building V from source on this machine is
documented as failing from an agent shell (failed SetHandleInformation), so
I could not test 3c5f448 directly and did not pretend to.

Also unverifiable by anyone: no released V has json2 at all, so 0.5.2 could not
be tested in either direction.

One lead on the cause, flagged as a hypothesis

Both builds emit the same statement:

config__Cfg result = (config__Cfg){.name = _str_36};

but _str_36 is {"", 0, 1} in the failing build and an unrelated long
array.ensure_noscan message in the passing one. The same _str_N index naming
different literals across two programs is consistent with a collision or a
numbering computed over a differing module set. I diffed the emitted C, not the
symbol tables, so this is a place to start looking and not a diagnosis.

…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.
@metif12

metif12 commented Oct 10, 2026

Copy link
Copy Markdown
Owner Author

The compiler moved, the bug is gone, and two of my explanations died with it

Two commits since the last comment, both finishing audit items. The short version
is that the machine's compiler changed from bb0d229 to ef2ec06 while this
branch was open
, and the upstream bug stopped reproducing.

Verified, not inferred: the same reproduction across three fresh project roots
prints vails correctly every time, vails doctor in examples/dialog reports
vails.json : ok, and vails dts regenerates. That unblocks the regeneration
this whole investigation started from, so the three checked-in
examples/*/frontend/vails.d.ts were regenerated — 11 added lines, no churn
— and now carry the blocking-command JSDoc that services/dts.v has emitted
since the previous commit.

A V maintainer had already closed [vlang/v#29508] as completed on 2026-10-05,
which is before I measured the non-reproduction here. So the fix is confirmed at
the source, not inferred from my own negative result — and the nine json2 commits
in range are left un-attributed, because nobody bisected which one did it.

Two explanations I had written down, both now killed

Both were in AGENTS.md §1b as theories. Neither survives a control:

  • "the _str_N literals collide." Both builds emit
    config__Cfg result = (config__Cfg){.name = _str_36}; but define _str_36
    differently, which reads exactly like a numbering collision. It is not: two
    programs that differ 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 the index its own
    string table assigns. So index divergence is the normal state between any two
    programs with different module sets and cannot be the cause.
  • "a module named cfg is special too." It failed to build where every other
    name built. It is the harness: duplicate of an import symbol 'cfg' is a
    variable named cfg colliding with import cfg — the struct is Cfg and
    cfg is the natural local name. Decisive control: a module named zzz with a
    variable zzz fails identically, and module cfg with the variable renamed
    decodes fine.

buildplan/json2_import_test.v is unchanged, and that is deliberate

It asserts net.http keeps one importer, that this importer and the json2.decode
instantiators stay disjoint, and that cli is where the two meet. That invariant
holds under the corrected trigger and is about this repository's test layout, so
the guard earns its place whether or not V ever regresses again. A second
net.http importer, or a net.http import landing in a decoding module, goes red
at review time instead of at vails doctor time.

The last audit item is closed

vails doctor no longer asserts one machine's path. The webview line used to
check 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() — written and tested for exactly
this, and previously with no production caller — and a new toolchain line names
the root and where it came from.

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
as before; a set one follows, and anything missing (webview.h,
libwebview.dll.a, the bin directory) is listed once here instead of surfacing
as a header error three minutes into a build. Measured with VAILS_TOOLCHAIN
pointed at a nonexistent root: it now reports that root and the missing pieces,
where the old code reported the default root as healthy.

The side-by-side DLL 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.

CI

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.
@metif12
metif12 merged commit d01e7b1 into main Oct 13, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant