Stage 1 review fixes, and Stage 2: the broker, the CLI and the module

The Stage 1 review (docs/reviews/2026-10-04-stage1-review.md, verdict
yes-with-fixes) found a real bug, and it was the kind Stage 2 would have
cemented. All five findings:

(1) HIGH, and reproduced before fixing: `key` resolved the action and
    then used only its `code`. So `keyboard key A` sent a bare code 30
    and the window received `a`; on `de`, `at` lost its level-three mask
    and typed `q`. `type` was the only path that used the mask, which is
    why every `type` test stayed green. `key` now sends
    modifiers(baseline | mask) before the down and restores the baseline
    on the up -- the one-character `type` sequence -- and `Shift_L`
    keeps its key-then-mask order, which is the other path on purpose.

    The same hole aliased two names onto one keycode: `down A` then
    `down a` recorded both and pressed 30 twice, Hyprland dropped the
    second, and the held set lied until the lease ended. A second name
    for a code already down is now refused.

(2) HIGH: the shutdown comment claimed hyprland-conf.nix sets
    input:virtualkeyboard:release_pressed_on_close. It did not. The line
    is there now, with the note that it releases keys and still never
    clears a mask -- which is why release_all zeroes the mask on every
    path we control rather than relying on it.

(3) MEDIUM: nothing would have noticed the keymap upload stopping. A
    `main` that connected and listened without uploading passed every
    test in the tree. Now asserted on the real sink: uploaded once,
    before `listen` (one shared ordering log across both stand-ins), the
    payload NUL-terminated with `size == len(utf8) + 1` read back
    through the fd, format 1, one terminator not two, and modifiers(0)
    straight after.

(4) LOW: `key` up now forgets the name only after a successful send,
    like `button` -- otherwise a raise between the two leaves us
    believing a key is up that the compositor still has down, and
    release_all will not try again.

(5) LOW: `\r` no longer aliases to Return (CRLF would have become two
    newlines silently), and an empty layout is refused -- xkbcommon
    compiles "" as the same keymap as `us`, so `--xkb-layout ''` looked
    configured and typed `us`.

Several of the review's named false passes are closed too: Control's
mask is compared against mod_get_index("Control") rather than merely
"not Shift's"; the keymap text assertion names pc_us_inet/pc_de_inet
instead of substring-matching "us"; the capital-under-Control case
asserts the whole sequence; the exit-code mirror is compared against
hhstreamd.protocol; and the module's defaults are read out of
nix/module.nix rather than asserted against themselves.

Stage 2 proper:

  * broker verbs keyboard.key / keyboard.type, both in the mutation set,
    both through _refresh (so they refresh the lease and, like every
    pointer verb, do NOT count as activity)
  * the driver's `kind` token mapped: a bad keysym or character is
    invalid_argument (exit 2), a missing keyboard global stays
    driver_refused (exit 10). The 4096-scalar cap and the shape checks
    are broker-side, because only a broker-side invalid_argument is 2
  * keys[] on pointer.state, keys_lifted[] on pointer.release and on
    pointer_lease_timeout, one release_all for both halves
  * CLI `session keyboard type|key|down|up`, reusing the pointer lease
    and its cache; `type` takes one raw argument and interprets nothing;
    the audit records a character count and never the text
  * sessions.keyboard.{layout,model,variant,options} on the unit's argv,
    layout defaulting to "us" with a type that refuses a comma. NO
    [keyboard] TOML table: hhstreamd reads that file and the driver is a
    different unit, so it would be a setting with no effect
  * CONTRACT-sessions.md bumped to v3; README.dev.md item 3 and
    vm-pointer.nix's header corrected (both still said the conf ships
    follow_mouse = 0 and that the keyboard work would choose)

And the operator decision that acquire grabs both devices: it now sends
two warps a real pixel apart, because one warp onto an idle cursor moves
the cursor and not keyboard focus. follow_mouse_threshold = 0 is set
explicitly in hyprland-conf.nix since the second warp depends on it,
`dispatch focuswindow` is the fallback when the nudge cannot be sent,
and the reply and audit carry which mechanism ran. The acquire test
asserts the pair and that they floor to different pixels -- a test that
only saw wl_pointer.enter would pass while the first keystroke went to
the wrong window.

  nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
  605 passed in 27.11s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-04 04:11:24 +00:00
1 parent b1f2744cf0
commit e6f4c3bb3f
24 files changed
+2474 -105

No files matched your search

+44 -6
View File
@@ -95,6 +95,20 @@ def test_the_two_allowed_control_characters_are_named_keys(us, character, code):
assert action.mask == 0
def test_a_carriage_return_is_refused_rather_than_aliased_to_return(us):
"""Only `\n` and `\t` are exempt from the C0 rule.
A `\r` silently typed as Return means a caller who pasted CRLF gets two
newlines per line and no way to find out, so it is refused with the rest
of the C0 block.
"""
with pytest.raises(keymaps.UnknownKey) as caught:
us.resolve_text("\r")
assert "scalar 0" in str(caught.value)
assert "U+000D" in str(caught.value)
def test_an_empty_string_is_no_actions_and_not_an_error(us):
assert us.resolve_text("") == []
@@ -132,6 +146,18 @@ def test_an_unknown_keysym_name_is_refused(us):
us.resolve_name("NoSuchKeysymAtAll")
def test_an_empty_layout_is_refused_rather_than_compiled_as_us():
"""xkbcommon compiles `""` as the *same keymap as `us`*.
So `--xkb-layout ''` would look configured, type `us`, and never say
otherwise -- the same class of silent-wrong-layout as the comma below.
"""
with pytest.raises(keymaps.KeymapError) as caught:
keymaps.build(layout="")
assert "layout" in str(caught.value)
def test_a_comma_separated_layout_is_refused_before_anything_is_compiled():
# xkbcommon accepts `us,ru` happily and hands back a two-group keymap. v1
# always sends group 0, so the second group would be silently unreachable:
@@ -191,8 +217,18 @@ def test_a_lock_is_not_a_modifier(us):
assert us.modifier_mask(name) == 0
def test_control_contributes_a_mask_that_is_not_shifts(us):
assert us.modifier_mask("Control_L") not in (0, shift_mask(us))
def test_control_contributes_the_bit_the_keymap_gives_control(us):
"""The *right* bit, not merely a different one from Shift's.
"not 0 and not Shift" is satisfied by Alt's bit, and every wire assertion
compares against `modifier_mask(...)` -- so a consistently wrong bit would
be consistently wrong and green. This asks the keymap for the index.
"""
expected = 1 << us._keymap.mod_get_index("Control")
assert us.modifier_mask("Control_L") == expected
assert us.modifier_mask("Control_R") == expected
assert expected not in (0, shift_mask(us))
# -- a second layout, which is what stops a Shift special case ---------------
@@ -227,10 +263,12 @@ def test_a_character_us_cannot_type_is_ordinary_on_de(us, de):
def test_the_keymap_text_is_an_xkb_keymap_naming_its_layout(us, de):
assert us.text().lstrip().startswith("xkb_keymap {")
# The symbols section names the layout, which is what the VM check greps to
# prove the keymap a client decoded with is the one we uploaded.
assert "us" in _symbols_line(us)
assert "de" in _symbols_line(de)
# The exact symbols names, not `"us" in ...` -- which is true of every
# us-family map and would stay true of a `de` keymap that had silently
# compiled as `us`. These are also the strings the VM check should grep,
# so they are written down once here.
assert 'xkb_symbols "pc_us_inet(evdev)"' in _symbols_line(us)
assert 'xkb_symbols "pc_de_inet(evdev)"' in _symbols_line(de)
def _symbols_line(keymap: keymaps.Keymap) -> str: