Files
hyprland-headless-stream-pl…/docs/reviews/2026-10-04-stage1-review.md
T
HermenixandClaude Opus 5 e6f4c3bb3f 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
2026-10-04 04:11:24 +00:00

32 KiB

Stage 1 review — the driver learns to type

Reviewed f931858 only (keymap, vendored zwp_virtual_keyboard_v1, ops, backend upload, __main__ flags, the pointer-side lease mirror, and tests/pointer/). Uncommitted edits under src/hhstreamd/, src/hhstream_session/, nix/module.nix and nix/hyprland-conf.nix are not this commit and were not reviewed. b1f2744, which lands after f931858 and only edits the plan and the Stage 0 write-up, was not reviewed either.

The suite was not re-run. The resolver and the dispatcher were executed against the installed libxkbcommon 1.13.2 (python-xkbcommon 1.5.1) for us and de. Line numbers below are f931858.

Verdict

Yes-with-fixes. type of A on us is the worked example, and it is not a Shift special case: the same path sends level 3 for de @. The uploaded text is a real XKB keymap (xkb_symbols "pc_us_inet(evdev)", TEXT_V1), and its NUL-inclusive size for us/pc105 is 35572, the same number Stage 0 logged. The layout is --xkb-layout (default us), not a hardcoded string. Nothing in this commit treats pointer acquire's one warp as keyboard focus.

Two things are wrong enough that Stage 2 will encode them if it starts from this tree. key throws away the mask the resolver just computed, so keyboard key A types a. And the shutdown comment says nix/hyprland-conf.nix sets input:virtualkeyboard:release_pressed_on_close, which this commit does not do.

Findings

  1. High. key drops action.mask, so any keysym above level 0 is sent as the bare key. keymap.py resolve_name("A") returns (code=30, mask=1) and resolve_text("@") on de returns (code=16, mask=128), which is ISO_Level3_Shift's bit, not Shift. _op_type uses that mask (ops.py:315, mask before the down/up, restored after). _op_key does not. On down it sends action.code and then, only if is_modifier(name), modifier_mask (ops.py:261-266). A and at are not modifiers, so the calls are key(30, pressed) and key(16, pressed) with no modifiers at all. Confirmed by running the dispatcher: {"op":"key","key":"A"} produces [("key", 30, 1)]; {"op":"key","key":"at"} on de produces [("key", 16, 1)]. The plan's NAME list includes A (2026-10-03-keyboard-input.md CLI block). Stage 2's keyboard key / down / up as a thin wrapper of this op will type the level-0 character. Stage 3's keyboard type assertion stays green while that is true, because type is the path that was tested (tests/pointer/test_ops.py:513-527).

    The same hole aliases two names onto one evdev code. down A then down a records both names and sends key(30, pressed) twice. Hyprland drops the second press (m_pressed already contains 30). release_all then emits two ups of 30 (ops.py:351-352); the second is dropped because the code is already up. The seat survives. The held set lied the whole time.

    Cheapest fix: in _op_key, if action.mask is non-zero, send modifiers(baseline | action.mask) before the down and restore the baseline on the matching up — the one-character type sequence — and refuse a second held name whose evdev code is already down, kind=invalid_argument. Do not store action.mask in _keys as the contribution: that field means "what this key adds", and type treats a zero contribution as "non-modifier, refuse". Shift_L must stay key-then-mask; the tests at test_ops.py:481-486 lock that order, and it is the other path on purpose.

  2. High. The comment says Hyprland releases keys on destroy. The conf file does not. __main__.py:186-193 says SIGKILL is safe because nix/hyprland-conf.nix sets input:virtualkeyboard:release_pressed_on_close. In f931858 that file's input block is follow_mouse = 1 and nothing else (nix/hyprland-conf.nix:81-94). The verification's change 4 was "required before code" because the default is 0 and releasePressed emits key-ups only when the option is true: a kill -9 leaves the code in the seat's m_pressed, and the next driver's down of that code is ignored. The clean path is fine — _lift_everything calls release_all, and release_all does send the ups and, when a mask was touched, modifiers(0,0,0,0). The comment describes the path the option exists for, and the option is not there.

    Cheapest fix: one line in nix/hyprland-conf.nix, input:virtualkeyboard:release_pressed_on_close = true, plus the sentence the verification asked for (the true setting still does not clear a mask, which is why modifiers(0,…) stays). Delete the claim from __main__.py until the line exists. This is not optional follow-up: it is the difference between a killed driver and a key that stays dead.

  3. Medium. The upload is right, and no test would notice if it stopped being right. WaylandSink.upload_keymap (backend.py:209-253) creates one keyboard, writes text.encode("utf-8") + b"\0", passes format=XKB_V1 (1) and len(payload), _sync()s, and only then os.closes the fd. python-xkbcommon 1.5.1's get_as_bytes defaults to XKB_KEYMAP_FORMAT_TEXT_V1 and ffi.string strips the NUL, so the extra byte is exactly one terminator, not two. For us/pc105 that size is 35572. __main__.py:155-173 calls it once, after connect, and returns exit 10 on CompositorUnavailable before listen. type never calls it.

    Nothing asserts any of that. test_the_keymap_object_is_built_once_and_reused_across_types (test_keymap.py:279-293) checks dispatcher._keymap is us. The sink has no keymap method. The verification named this false pass: a backend that uploads on every type stays green. test_a_usable_layout_gets_as_far_as_the_compositor (test_driver_flags.py:128-138) raises at connect, so upload, the NUL, format 1, and "before listen" are never reached. A main that connects and listens without uploading passes every test in the tree. test_the_backend_binds_the_keyboard_manager_at_version_1_and_survives_its_absence (test_vendored_protocol.py:179-187) constructs an unconnected WaylandSink and checks the flag is false. A connect that ManagerTooOlds when the keyboard global is missing stays green.

    Cheapest fix: one test with a sink whose connect succeeds and whose upload_keymap records (text, caller). Assert main calls it once, with a payload whose last byte is NUL and whose length is len(text.encode()) + 1, and that serve is what runs next — inject listen so it does not need a socket. A second test calls upload_keymap on a fake keyboard object and asserts keymap(1, fd, size) sees size == len(payload) while fd still reads back the bytes. Do not assert only that keymap.py returns equal strings.

  4. Low. key up forgets the name before the send, unlike button. _op_key pops _keys and then calls sink.key (ops.py:275-276). _op_button updates _pressed only after the send (ops.py:198-203). A raise from the up — KeyboardUnavailable is caught in __main__.py:211-214 and the process stays up — leaves _keys empty while the compositor still has the code down. release_all will not repeat the up. Confirmed with a sink that raises on state=0: after a failed Shift_L up the held set is [] and _mask_touched is still true, so the next release_all sends modifiers(0,…) and no key-up. Not reachable today unless the keyboard object disappears between down and up (close is the only thing that clears it, and it runs after the lift). Cheapest fix: pop after a successful send, same order as the button.

  5. Low. Two layouts xkbcommon accepts are not the layout the caller named. CONTROL_KEYSYMS maps \r to Return (keymap.py:67). The plan's C0 rule exempts \n and \t only; \r is a Return and not a refusal. And build(layout="") does not raise: xkbcommon compiles it as xkb_symbols "pc_us_inet(evdev)", the same keymap as us. A hand-run --xkb-layout '' looks configured. The comma check (keymap.py:144-153) is the right idea and does not cover this. Cheapest fix: drop \r from CONTROL_KEYSYMS, and reject an empty layout in build() next to the comma check.

Not defects, checked because they look like them:

  • Shift is not hardcoded. A on us is evdev 30 and mask 1 << mod_get_index("Shift") (index 0, so 1). de @ is evdev 16 and mask 128, equal to modifier_mask("ISO_Level3_Shift"), not equal to Shift. type "@" emits modifiers(128), key(16, down), key(16, up), modifiers(0,…) and no code 42. Control's contribution is 4 (index 2). The measured modifier set on us/pc105 is exactly EXPECTED_MODIFIERS; Meta and Hyper are absent because no key produces them. Locks are Caps_Lock and Num_Lock, and type while either is held emits nothing.
  • Unmappable means no events. resolve_text("xéy") raises UnknownKey with scalar 1 (U+00E9) and neither the character nor the string. The dispatcher calls resolve_text before any sink call (ops.py:310-311). é, a C0 other than the two (and \r) exemptions, a dead keysym, and 4097 scalars are the same shape.
  • The 4096 cap counts scalars. len(str) is what resolve_text compares (keymap.py:335-338). 4096 copies of 😀 miss the cap and fail on scalar 0; a byte cap would have said "limit".
  • Degraded mode is the reachable one. A missing manager makes upload_keymap return before create_virtual_keyboard (backend.py:221-226). has_keyboard() stays false. key / type answer kind: refused (ops.py:391-396). release_all sends key-ups only when _keys is non-empty and modifiers(0,…) only when _mask_touched (ops.py:347-361). Both stay empty if no keyboard op ever succeeded, so the button half still runs. The test uses a real us keymap plus a sink with no keyboard (test_ops.py:703-723), which is how the process actually starts: the keymap is compiled before connect (__main__.py:132-138) even when the global is absent.
  • No keyboard frame, no _aimed() on key or type, no touch. frame remains the pointer op. release_all still frames pointer outputs and does not add one for keys (ops.py:343-344, locked by test_ops.py:667-683). There is no touch in the driver. This commit does not add broker verbs, so it does not add any to the mutation set either.
  • The driver token exists, on the driver reply only. A bad keysym, an unmappable scalar, a bad state, and a string over the cap are {"ok": false, "kind": "invalid_argument"} (ops.py:112-117, 159-160, 413-425). A missing keyboard is kind: "refused". A bad layout is process exit 2 before WaylandSink is constructed (__main__.py:132-141, keymap.py:144-153). Upload failure is exit 10 and does not listen (__main__.py:155-164). The committed broker does not read kind. That is the next section, not a second copy of this one.
  • Focus. No Stage 1 path warps to deliver wl_keyboard.enter, warps twice, or calls dispatch focuswindow. type with no prior warp emits keys (test_ops.py:420-432). pointer acquire is still one _warp. The Stage 0 misreading was not built on.

Tests

Dispatcher tests record tuples. They cannot see Wayland time, the keymap fd, or format. That seam is fine for ops and blind for the upload. Per test, what a pass requires, and where a pass is a lie:

tests/pointer/test_keymap.py (real xkbcommon, not a stub):

Test Passes only if False pass
test_a_lower_case_letter_… resolve_name("a") is (30, 0) Asserting the XKB code 38 would be the lie; this one asserts 30
test_a_capital_is_the_same_code_with_shift_in_the_mask code 30 and mask == 1 << mod_get_index("Shift"), and the code is not 42 Hardcoding mask 1 is what this test refuses. It does not run type
test_shift_is_a_key_in_its_own_right_… Shift_L is (42, 0) and modifier_mask equals that Shift bit
test_a_named_keysym_resolves_… Return 28, Tab 15, BackSpace 14, Left 105 The mask is not checked. All four are level 0 on us, so a resolver that always returns mask 0 passes
test_the_two_allowed_control_characters_… \n and \t are Return / Tab, mask 0 Does not notice that \r is also Return
test_an_empty_string_… resolve_text("") == []
test_a_character_this_layout_cannot_produce_… UnknownKey, message contains scalar 0, and the character is not in the message A message that quoted é fails this. Logging the string elsewhere would not
test_the_refusal_names_the_index_… "abcé" says scalar 3 and not é
test_a_dead_keysym_is_refused_by_name dead_acute raises and the message contains dead key The prefix check refuses the name even when it is not on the layout. The test does not prove a layout that has the key still refuses it; us does not have it
test_an_unknown_keysym_name_… NoSuchKeysymAtAll raises UnknownKey
test_a_comma_separated_layout_… build("us,ru") raises KeymapError and the message contains group Compiling the two-group keymap and then raising still passes. The user-visible failure (nothing uploaded) is the same
test_a_layout_xkbcommon_rejects_… zzz-no-such-layout raises and the name is in the message xkbcommon does reject it (NULL, not a silent us). Empty string is the case this does not cover: it compiles as us
test_the_cap_is_exactly_at_the_limit 4096 as resolve
test_one_scalar_over_the_cap_… 4097 raises and the message names 4096 No sink. The dispatcher twin covers "zero calls"
test_the_cap_counts_scalars_and_not_bytes 4096 emoji (len == 4096, UTF-8 longer) raises scalar 0 and the message does not contain limit An ASCII-only cap test would not tell a byte cap from a scalar cap. This one does
test_the_modifier_set_is_measured_… modifier_names() == EXPECTED_MODIFIERS An empty set fails. It does not fail a set that matches the constant and was then hardcoded — the constant is what us/pc105 measures, which is the point of the constant
test_a_lock_is_not_a_modifier locks are exactly {Caps_Lock, Num_Lock}, none of them modifiers
test_control_contributes_a_mask_that_is_not_shifts Control's mask is neither 0 nor Shift Alt's bit passes. Nothing asks mod_get_index("Control"). The wire tests compare against modifier_mask(...), so a consistently wrong bit stays green. Measured here: index 2, mask 4. The test does not lock that
test_de_swaps_y_and_z_… us y/z are 21/44, de is 44/21 A table beside the keymap that always returns the us codes fails
test_on_de_the_at_sign_… us @ has Shift's mask; de @ is neither 0 nor Shift, and equals modifier_mask("ISO_Level3_Shift") The two sides use different xkbcommon calls (level lookup vs a pressed key). Both are 128. A Shift special case for letters only would still pass, which is why the de case exists
test_a_character_us_cannot_type_is_ordinary_on_de ü raises on us; on de it is udiaeresis, mask 0
test_the_keymap_text_is_an_xkb_keymap_naming_its_layout text starts with xkb_keymap {; the xkb_symbols line contains us or de "us" in "pc_us_inet(evdev)" is true of every us-family map. The de line is what fails if the layout argument is ignored. It does not require the symbols name pc_de_inet(evdev), which is what the VM grep should match. Actual lines: xkb_symbols "pc_us_inet(evdev)" and xkb_symbols "pc_de_inet(evdev)"
test_an_unmappable_character_emits_nothing_through_the_dispatcher type "abcé" is ok: false, kind == invalid_argument, sink.calls == [] "No event carried é" would pass with a and b typed. This assertion would not
test_a_string_over_the_cap_emits_nothing_… 4097 as, same three checks
test_the_keymap_object_is_built_once_… two types leave dispatcher._keymap as the same object The false pass the verification named. Re-uploading per string never calls this object twice and stays green

tests/pointer/test_ops.py, new cases. All of them talk to RecordingSink, which writes down whatever it was told. A pass means the dispatcher passed those tuples, not that zwp_virtual_keyboard_v1.key was marshalled.

Test Passes only if False pass
test_the_contracts_ops_are_exactly_what_is_implemented Dispatcher._ops equals a set literal that includes key and type and not release_all_keys The docstring says the contract. The test never opens CONTRACT-sessions.md. §3.4 still lists neither op, and this stays green
test_key_down_sends_the_code_and_lists_the_name key down Return → [("key", 28, 1)] and pressed says ["Return"]
test_key_needs_no_warp type "Hi" and key a both ok on a dispatcher that never warped, and some call is key(30, down) The in sink.calls check is weak (H is not code 30; the explicit key a supplies it). ok is True on type "Hi" is the real assertion, and a call to _aimed() fails it. Not a false pass of the aim rule
test_a_key_is_not_tagged_with_an_output_… after a warp, key a is exactly [("key", 30, 1)] A sink that accepted an output argument and ignored it would still look like this, because the dispatcher never passes one. That is what the arity assertion is for
test_key_up_forgets_the_key down then up is down, up, and lifted == ["a"]
test_up_of_a_key_that_was_never_down_… ok, lifted == [], no sink calls
test_keys_are_reported_oldest_first pressed names are Control_L, Shift_L, a Does not look at the sink, so a modifier down that forgot the mask still passes
test_a_modifier_down_sends_the_key_and_the_mask Shift_L down is key 42 then modifiers(mask, 0, 0, 0)
test_a_modifier_up_restores_the_mask_… releasing Shift while Control is held sends key-up 42 then Control's mask, not zero
test_an_ordinary_key_down_sends_no_mask key a is exactly one key call This is also why key A has no test. The ordinary-key assertion is what a capital would satisfy, wrongly
test_type_of_a_capital_is_the_mask_and_not_a_shift_keycode exactly modifiers(shift), key(30,1), key(30,0), modifiers(0,0,0,0), and no code 42 "Some call had code 30" would be the lie. This list is the worked example. It uses modifier_mask("Shift_L"), which on this keymap is 1
test_type_leaves_no_key_held type "Hello" leaves pressed keys empty Does not look at the sink
test_type_emits_a_down_up_pair_per_character the key calls for "ab" are 30 and 48, down/up each Filters to key calls. Omitting every modifiers stays green. The capital test is what locks the mask
test_type_of_an_empty_string_… ok, no calls
test_type_ors_an_explicitly_held_modifier_… down Control_L then type c is modifiers(control), key down/up of c's code, modifiers(control) again; pressed is still ["Control_L"]; no key 29 Full sequence. Not a false pass
test_type_of_a_capital_under_a_held_control_… first call is modifiers(control|shift), last is modifiers(control) modifiers(both) then modifiers(control) with no key events passes. The key, and "no second Control down", are not in the assertion
test_type_while_a_non_modifier_is_held_… ok: false, kind invalid, no new calls, a still held
test_type_while_a_lock_is_held_… Caps_Lock held, type a is ok: false, no new calls Does not check kind. A refused (exit 10) passes
test_a_string_that_fails_on_its_third_character_… "abé" is ok: false and calls == [] Same strength as the keymap twin. Does not check kind
test_a_bad_character_is_a_usage_error_and_a_missing_keyboard_is_not é, Nope, and state=sideways are invalid_argument; the same type a on KeyboardlessSink is refused This is the token. It does not check that anything maps the token to exit 2. Nothing in f931858 does
test_without_a_keymap_at_all_… Dispatcher(sink, None) still warps and buttons; type is refused
test_release_all_lifts_keys_in_press_order_then_zeroes_the_mask Control_L then a lifts 29, then 30, then modifiers(0,0,0,0)
test_release_all_lifts_keys_after_buttons_and_adds_no_keyboard_frame button up, one pointer frame, key up 42, modifiers(0,…) Locks the frame before the key-up. The plan's step list puts the pointer frames last. Buttons and keys are different objects; the frame does not gate the key. Not a false pass, and not worth reordering unless a client is shown to care
test_release_all_lifts_keys_even_after_a_warp_to_another_output after a warp to another output, the only call is key(30, up) A plain a never touched the mask, so the absent modifiers is correct (_mask_touched is false). A sink that ignored an output argument cannot fake this: the call has no output slot
test_release_all_without_a_keyboard_still_lifts_buttons keymap present, has_keyboard false, a held button: lifted == ["left"], lifted_keys == [], and the calls are button up plus frame KeyboardlessSink.key raises. If the key half ran, the test errors rather than passes. It does not hold a key, which is the only degraded state the process can reach
test_release_all_after_a_type_zeroes_the_mask_once_more after type A, release_all is exactly one modifiers(0,0,0,0) _mask_touched stays true after type restores the baseline. A type that never sent a non-zero mask would not take this branch; type a is not this test

tests/pointer/test_driver_flags.py:

Test Passes only if False pass
test_the_xkb_flags_default_to_the_frozen_values parse_args([]) is us / pc105 / empty variant / empty options Parsing only. main could ignore them; the refusal tests below are what catch that for a bad value
test_the_defaults_are_the_ones_the_module_option_defaults_to the two Python constants equal ("us", "pc105") Does not read nix/module.nix. In f931858 the unit's ExecStart is still the two-flag line (nix/module.nix:986-992) and there is no sessions.keyboard option. The docstring says the module and the binary cannot drift. They are not compared
test_a_layout_is_taken_from_the_flag parse_args(["--xkb-layout", "de"]).xkb_layout == "de" Parsing only
test_the_contract_command_line_still_parses the §3.4 line plus the four XKB flags parses The contract text is not read, and it does not yet contain those flags
test_a_comma_separated_layout_exits_2_without_connecting main(["--xkb-layout", "us,ru"]) is exit 2 and WaylandSink was never constructed The injected sink raises if constructed. A connect that happened would fail the test, not pass it
test_a_layout_xkbcommon_rejects_exits_2_without_connecting zzz-no-such-layout is exit 2, same injection Ignoring the flag and always compiling us would reach connect and fail this. The flag is actually wired
test_a_usable_layout_gets_as_far_as_the_compositor main(["--xkb-layout", "us"]) raises _Unreached("connect") Stops at connect. See finding 3
test_the_exit_codes_match_the_brokers_table the three constants are 0, 2, 10 Does not import hhstreamd.protocol. Two copies can diverge and this still passes

tests/pointer/test_lease.py, the new key cases. They call press_key on the lease directly. None of them opens a socket. A pass does not mean a verb updates the mirror; no verb in f931858 does (manager.py never calls press_key).

Test Passes only if False pass
test_press_and_lift_one_key press_key / keys_pressed / unpress_key, and a later release has keys_lifted == []
test_lifting_a_key_that_is_not_down_… unpress_key of a key not held is []
test_keys_are_kept_in_press_order order is press order, including after one is removed; release().keys_lifted is what remained
test_pressing_a_key_twice_leaves_one_down a dict, so the second press_key does not duplicate The driver does not share this dict. A double key down still sends two presses; this test cannot see that
test_keys_and_buttons_are_tracked_separately release reports buttons and keys independently
test_a_non_holder_cannot_press_a_key LeaseInvalid for the other session
test_expire_still_returns_no_key_list_… read keys_pressed(), then expire(); the return has no keys_lifted and no buttons_lifted; the lease is then empty hasattr fails if someone adds the field to LeaseInfo. Widening the return is what this is for
test_expiry_does_not_leak_keys_to_the_next_holder after expire, the next acquire sees no keys

tests/pointer/test_vendored_protocol.py, the keyboard cases. The source-text tests pass if the generated file contains the substring, including in a comment. The two skipif tests import pywayland and check hasattr and version == 1, which is a real bind of the generated class, still with no display.

Test Passes only if False pass
test_the_keyboard_protocol_is_vendored_beside_the_pointer_one the package exists and every .py starts with the scanner banner
test_the_keyboard_manager_is_version_1_with_the_seat_only_request the source contains the interface name, version = 1, create_virtual_keyboard(self, seat: WlSeat), and not WlOutput A comment with that signature passes
test_the_keyboard_carries_keymap_key_and_modifiers source contains the three signatures, ArgumentType.FileDescriptor, and no def frame( Same
test_the_integers_the_xml_names_but_does_not_define_live_in_our_code the generated file mentions keymap_format and does not define the enum; XKB_V1 == 1; STATES is 0 and 1 Does not check that upload_keymap passes 1. A call with format 2 stays green
test_the_shim_resolves_the_keyboard_relative_import the manager module imports WlSeat from ..wayland
test_the_keyboard_protocol_binds_against_the_installed_pywayland import, name, version 1, and the four requests exist on the proxy Skipped when pywayland is absent. The package check is what runs in the build
test_the_backend_binds_…_and_survives_its_absence KEYBOARD_MANAGER_VERSION == 1 and an unconnected sink reports no keyboard See finding 3. It never runs _on_global
test_the_backend_refuses_a_version_1_manager ManagerTooOld(1) mentions version 1 and create_virtual_pointer_with_output This is the pointer manager. It says nothing about a keyboard global at the wrong version. _on_global binds KEYBOARD_MANAGER_VERSION whenever the name matches (backend.py:362-366) and does not reject a compositor that advertised something else

tests/pointer/test_pointer_server.py only grew keys / lifted_keys in two assertions. A pass means the JSON reply gained those fields. It does not send key or type.

What Stage 2 must not assume

Three of these, left alone, make Stage 2 wrong. The rest are the same class of mistake at lower cost.

  1. {"op":"key","key":"A"} does not type A. Neither does at on de, or any other keysym whose producing mask is non-zero. type does, and it ORs that mask with the baseline of keys that are actually modifiers. keyboard key / down / up must not be "send the name through unchanged" until finding 1 is fixed, and a VM check that only runs keyboard type will not catch it. a and A are two held names for evdev 30. Caps_Lock down sends the key and never a locked mask; type then refuses. Do not document Caps as capitalization.

  2. kind does not survive the broker client, and every refusal is exit 10. PointerDriver._exchange raises DriverRejected from reply["error"] and drops everything else (src/hhstreamd/driver.py:158-159 at f931858). _drive maps every DriverRejected to driver_refused (manager.py:2047). A Stage 2 test that asserts exit 2 for é fails, or it passes by reading the English. Read kind off the JSON before that conversion and map invalid_argument to exit 2. Leave refused as exit 10. The 4096 check lives only in resolve_text. A broker check of len(text.encode()) disagrees with it on the emoji case the driver already got right. Rejected text carries an index; do not log text, and do not put it on keyboard_type.

  3. Do not design the enter subtest, the unit argv, or kill -9 from the comments in __main__.py. pointer acquire is still one warp (manager.py _warp, unchanged in this commit) and Stage 0's (a1) did not deliver wl_keyboard.enter. A second warp to the same floored pixel is not the fix. nix/module.nix does not pass --xkb-layout; the flag defaults to us, so the running unit types us until Stage 2 adds the argv. A [keyboard] table in the broker TOML is still not the upload — the driver never opens that file. input:virtualkeyboard:release_pressed_on_close is not set, whatever __main__.py:191-193 says. upload_keymap is not idempotent: a second call creates a second virtual keyboard and orphans the first (backend.py:227). Do not call it on acquire or per string.

Also, because the mirror landed here and nothing uses it:

  • expire() still returns LeaseInfo with no keys (pointer.py:178-196). _expire_pointer reads pressed() and not keys_pressed() (manager.py:1857). Read the keys first. The driver's one release_all is what lifts them; do not add release_all_keys.
  • The committed PointerDriver.release_all returns the button list only (driver.py release_all), and _release_all_buttons does list(lifted) (manager.py:2058-2061). The new reply field is lifted_keys beside lifted. Changing the client method to return a tuple without updating that list() turns the button names into the two lists.
  • pressed() on the client still returns buttons only. The reply now also has keys. Do not widen the return of pressed() in place.
  • keyboard.key and keyboard.type are not in MUTATING_VERBS. pointer.state must stay out of it. No keyboard verb calls touch. Acquire's stderr still says "pointer" only; a keyboard.* verb that goes through _refresh moves the deadline, and the help text has to say so.
  • CONTRACT-sessions.md §3.4 is still the two-flag command line and a pressed / release_all with no key fields (:262, :283-284). Amend it in the same change as the unit argv. test_the_contracts_ops_… will not notice if you forget.

Carried objections

From the Stage 0 review, still true of f931858, with one correction for where the branch tip is:

  • The plan banner is not in this commit. git grep of f931858 for the supersession banner is empty, so anyone who builds Stage 1 from that commit alone still has the unedited exit-code paragraph, the [keyboard] TOML rows, and "if it repeats, the help text says so". b1f2744 (after this commit, not reviewed here) adds the banner and folds the eight rows. Do not treat that as something Stage 1 did, and do not do it again.
  • Stage 0's (a) mechanism, as f931858 inherited it. This commit does not cite it. The parent commit's README did. b1f2744 rewrites that README; it was not re-checked for this review. Stage 2 still must not read "one warp late" as "wait longer" or as "warp twice to the same point".
  • mask_cleared=no is not a held Shift. backend.py:246-250 cites tests/README-keyboard-probe.md for "destroy does not clear the modifier mask". The send of modifiers(0,0,0,0) after upload is right anyway — releasePressed never emits modifiers — but the citation is the sentence Stage 0 said the log does not support. The cleanup state=0 for code 30 is the poison evidence, and it is why finding 2 is not theoretical.
  • The Hyprland XML, kept on purpose. regenerate.py says wayland-protocols has no virtual-keyboard directory in this nixpkgs and vendors Hyprland's copy, which names keymap_format and key_state and defines neither. XKB_V1 = 1 and buttons.STATES are the right workaround. Switching later, if a nixpkgs grows the file, does not move the integers. Do not vendor a second copy to get an enum.
  • Changes 5 and 8, the halves this stage did not take. The driver half of 5 is done (flag, comma rejected before xkb_keymap_new_from_names, no rules flag, evdev hardcoded). The unit argv is not. The driver half of 8 is done (index and U+ codepoint, and the server does not log the request line). Acquire's stderr is untouched. Change 7 (the probe's expectations, the unconditional keyboard down warning) is not this stage; the warning has nowhere to live until the CLI exists, and it is still unconditional when it does.
  • xkbcommon is a hard dependency (pyproject.toml, nix/package.nix). Leave it that way. An optional one lets test_keymap.py skip, and the unmappable path is the one that rots.