Files
HermenixandClaude Opus 5 a6a4094e6a Stage 3: vm-keyboard, and the helper derivation that never built
The keyboard's only purpose is that a client receives symbols, so a unit
suite alone was testing the shape of a request nobody answered --
docs/TODO/scroll-has-no-compositor-proof.md is the precedent. This is
the compositor proof: two nixosTests, 16 subtests each, real time, no
injected clock.

  nix build --no-link -L .#checks.x86_64-linux.vm-keyboard
    test script finished in 281.06s   (16/16, exit 0)
  nix build --no-link -L .#checks.x86_64-linux.vm-keyboard-de
    test script finished in 278.15s   (16/16, exit 0)

The victim, checks/lib/keyboard_target.py, decodes every keysym from the
keymap the COMPOSITOR forwarded rather than from a table of its own.
That is the mutation rule PLAN §14 asks for: a driver that stopped
uploading leaves the client with nothing to decode with, every key
arrives as `sym=?`, and the character assertions go red. A victim with
its own keymap would decode `hello` either way and the check would be
asserting that the check can spell.

What the client actually reported, which is the point of reading back
the application's state rather than the broker's intention:

  type A        [(30, 1, 'A'), (30, 0, 'A')]   masks [1, 1, 0, 0]
                -- evdev 30 decoded as A, so the mask arrived BEFORE the
                   key, and no code 42 anywhere
  key Return    [(28, 1, 'Return'), (28, 0, 'Return')]
  TTL expiry    [(42, 1, 'Shift_L'), (42, 0, 'Shift_L')] masks [1,1,0,0]
                -- lifted by the sweeper alone, mask cleared with it
  chord         depressed mask [4, 4] while Control held, still held
                   after the type returned

It runs TWICE because `sessions.keyboard.layout` reaches the uploaded
keymap through exactly one path -- `--xkb-layout` on the driver unit's
argv -- and one layout cannot tell that path from a hardcoded `us`:

  us:  symbols=pc_us_inet(evdev)  bytes=35572
       type y -> [(21, 1, 'y')]   type z -> [(44, 1, 'z')]
       type cafü -> exit 2, "scalar 3 (U+00FC) is not typeable", and the
                    client reported [] -- no prefix typed
  de:  symbols=pc_de_inet(evdev)  bytes=37532
       type y -> [(44, 1, 'y')]   type z -> [(21, 1, 'z')]   (swapped)
       type cafü -> {'chars': 4, 'ok': True}
                    client decoded ['c', 'a', 'f', 'udiaeresis']

Hyprland's own input:kb_layout is left at `us` in BOTH runs, so a client
that ignored our keymap would decode the us answer on the de machine.

The decisive subtest is "acquire takes the KEYBOARD as well as the
cursor". With session B holding keyboard focus because its window mapped
last, acquire on A delivered wl_pointer.enter AND wl_keyboard.enter to A
and wl_keyboard.leave to B, with focus == "warp". A check that asserted
only pointer delivery would have gone green while A had the cursor, B
had the keys, and the first keystroke of the lease went to B -- which is
exactly what one warp does. §B3's "one warp" and the Stage 0 review's
"do not assert enter on acquire" are superseded by the two-warp acquire,
and the header says so.

One deviation from §B3, with reasons in the header: its subtest 4 says
`type y` decodes to sym `z`, which is wrong for a victim that decodes
from the forwarded keymap -- the same paragraph requires that. `type y`
resolves keysym y against the uploaded layout and sends that layout's
code; the client decodes it back to `y`. The sym is `y` on both layouts
by construction. What differs is the CODE, the symbols name, and whether
ü is typeable at all, and those are what this asserts.

── AND A PRE-EXISTING BUG THE FIRST RUN EXPOSED ──────────────────────

checks/lib/session-tools.nix opened a heredoc with `<<EOF` and closed it
with an INDENTED `  EOF`. A delimiter has to be at column zero, so it
never closed: it swallowed the rest of the builder -- both `install`
lines and every self-test -- into the shim's own text. The derivation
built anyway, with `hhs-ipc-watch` alone in $out/bin:

  $ ls /nix/store/wy3lp3...-hhstream-session-tools/bin/
  hhs-ipc-watch

So hhs-pointer-target has NEVER existed in that derivation either.
vm-pointer execs that absolute path, and vm-keyboard failed the same
way: the broker reported `target exited immediately (exit code 127)`,
which is true about a path that was never created and says nothing about
why. hhs-ipc-watch's own first line was `  #!...`, indented, which is
not a shebang, so vm-ipc is affected too. The build-time self-tests that
exist to catch exactly this had themselves become heredoc text. The
unquoted delimiter also expanded the swallowed text, so the builder ran
`hhstreamd.ipc` as a command.

The shim is a writeTextFile now -- no delimiter to indent wrong -- and
`test -x` on all three programs is the guard that would have caught it.

NOT DONE, and it needs doing: vm-pointer and vm-ipc have not been
re-run. checks/default.nix says one VM at a time on this two-core box
and I did not want to perturb the keyboard runs. That they WOULD have
failed is read off the store listing above, not off a run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
2026-10-04 20:23:14 +00:00

143 lines
4.8 KiB
Nix

# The guest the three session checks share: compositor, broker, one account.
#
# A function rather than a copy in each check, because what the three differ in
# is the *assertions*, not the machine, and three drifting copies of a machine
# definition is how a check quietly stops testing what its neighbour tests.
# Everything that varies is an argument; nothing here relaxes an assertion.
#
# It is a machine, not a test. `gpu-session.nix` supplies the two pieces of
# hardware a bare NixOS test machine lacks (see that file); this adds the
# module under test, the account applications run as, and the tools the guest
# needs to interrogate the compositor.
{
hhsModule,
hhstream,
hyprland,
testTools,
sessionTools,
foot,
jq,
procps,
grim,
coreutils,
dejavu_fonts,
}:
{
# The allowlist, as `sessions.apps` takes it.
apps,
pointer ? false,
# Only read when `pointer` is true; the module's own defaults otherwise.
leaseTtl ? 30,
leaseMax ? 300,
# The XKB layout the pointer unit uploads as its virtual keyboard's keymap.
# There is no `keyboard.enable`: the keyboard is the same unit, the same
# process and the same lease as the pointer, so `pointer = true` is what
# turns typing on. This is only the layout, and `vm-keyboard` is the only
# check that sets it to anything but the default -- it runs twice, once per
# layout, because the layout only reaches the keymap through this unit's
# argv and a second value is the only way to prove that.
keyboardLayout ? "us",
keyboardModel ? "pc105",
keyboardVariant ? "",
keyboardOptions ? "",
width ? 1280,
height ? 720,
fps ? 30,
sessionUser ? "hermes",
# Long enough that nothing is reaped by surprise mid-check, short enough that
# the number is visibly the test's and not the module's 3 h default.
idleTimeout ? 600,
# The group that owns the compositor's runtime directory. The module's
# default, named here because this fragment is a plain attribute set (the
# test driver's `nodes.<name>` does not take a function) and so cannot read
# it back out of `config`.
sessionGroup ? "hhstream",
# Appended to the generated hyprland.conf. Only `vm-pointer` uses it, and
# only for one line it has to override; see that file for the measurement.
extraConfig ? "",
}:
{
imports = [
hhsModule
./gpu-session.nix
];
services.hyprland-headless-stream = {
enable = true;
package = hhstream;
hyprlandPackage = hyprland;
inherit extraConfig;
# No `name`: the wildcard rule applies to whatever connector the virtio GPU
# gives this guest (see vm-hyprland.nix for why a check must not know it).
outputs = [
{
inherit width height;
refresh = fps;
}
];
sessions = {
enable = true;
user = sessionUser;
inherit apps idleTimeout;
pointer = {
enable = pointer;
inherit leaseTtl leaseMax;
};
keyboard = {
layout = keyboardLayout;
model = keyboardModel;
variant = keyboardVariant;
options = keyboardOptions;
};
};
};
# The module deliberately does not create this user: launched applications
# run as it, so it is normally a real person's account. `video` and `render`
# are what any client of this session needs to reach the GPU; the broker's
# unit adds the compositor's own group on top.
users.users.${sessionUser} = {
isNormalUser = true;
extraGroups = [
"video"
"render"
# The compositor's own group, on the *account*.
#
# The broker does not need this -- its unit has the group as a
# supplementary one, which is how the applications it launches reach the
# Wayland socket. This is for the other half of the CLI: `hhstream shot
# --output hh-<id>` runs grim as whoever typed it, and the frame socket
# and runtime directory are 0750/0660 owned by this group. The operator
# account on a real machine is in it for exactly that reason -- it is
# what `hhstream`'s `sg` re-exec exists to recover when a login predates
# the membership.
sessionGroup
];
};
# foot resolves "monospace" through fontconfig and refuses to start without a
# usable font; a NixOS test machine has `fonts.enableDefaultPackages = false`.
# One font, not the default set.
fonts.packages = [ dejavu_fonts ];
environment.systemPackages = [
testTools # hhs-hyprland-diagnostics
sessionTools # hhs-ipc-watch, hhs-pointer-target, hhs-keyboard-target
hhstream # the CLI under test
hyprland # hyprctl: the compositor is the source of truth here
foot
grim # per-container capture, which is what an output *is* for
jq # the in-guest predicates the bounded waits poll
procps
coreutils
];
virtualisation = {
memorySize = 2048;
cores = 2;
diskSize = 4096;
graphics = false;
};
}