Stage 2 fixes: the two tests the review named, and the docs drift
From docs/reviews/2026-10-04-stage2-3-review.md (Stage 3 done; Stage 2
done-with-fixes). Its findings 1, 2, 3 and 5, which it called the only
things standing before merge.
(A) REPLAY, THROUGH THE SINK. What existed was
`test_every_keyboard_verb_is_cached_for_the_same_reason`, which
asserts the two verbs are in MUTATING_VERBS -- and the verification
doc had already named that as the false pass: "asserting
`deduplicated` and not the sink. A handler that types and then sets
the flag stays green." Two integration tests now, modelled on
`test_a_retried_click_with_the_same_request_id_clicks_once`:
test_a_retried_type_with_the_same_request_id_types_once
`keyboard.type` of "ab" twice with request_id="retry-me".
Asserts `deduplicated`, chars == 2 on both, and that the sink
still has exactly 4 key events -- two characters, a down and an
up each -- so a replay that typed again is caught by the count
and not by the flag.
test_a_retried_unmappable_type_stays_refused_and_types_nothing
`café` twice with one id. Both refusals are `invalid_argument`,
the second carries `deduplicated` (a recorded failure is
replayed as the failure it was), and the sink is empty after
both -- there is no partial type on either call.
Mutation-checked rather than assumed: removing `keyboard.key` and
`keyboard.type` from MUTATING_VERBS fails both.
(B) KILL, THROUGH kill(). `test_killing_the_holder_lifts_its_keys` calls
`_drop_lease_for` directly, so it proves that helper lifts keys and
says nothing about whether `kill` still calls it. The integration
kill test now holds `Shift_L` before the kill and asserts the SINK
saw `("key", 42, 0)` and `("modifiers", 0, 0, 0, 0)` -- the lease
forgetting a key is not the compositor being told it came up, and
only the second matters to the application. Code 42 because `type`
never emits it, so the release cannot be a leftover.
Mutation-checked: stubbing out the `_drop_lease_for` call in
`kill()` fails it. Before this it stayed green.
(C) DOCS. The plan's stage table and risk paragraph still said acquire
is one warp and that `focuswindow` was unbuilt Stage 4 work. The
contract (v3 §4) describes what shipped; the plan did not. Rewritten
so they agree, and the plan now says outright that the contract wins
where they differ:
* risk 1 marked RESOLVED, describing the two warps, the pinned
`follow_mouse_threshold`, and `focuswindow` as the
nudge-failure fallback selecting on `address:` (not
`stable_id`, which is not a Hyprland selector)
* Stage 3 marked Done; Stage 4 struck as not existing -- the
answer to Stage 0 was the second warp, not a focus dispatch
* the top banner, the §5 VM assertion list and open question 2
no longer say "one warp"
* verification §B3 subtest 1 amended: it is a live assertion
rather than an expected red, and the check additionally requires
`focus == "warp"` so the fallback is not accepted as success
Also amended one sentence the review did not list, because leaving
it would contradict the edit above inside the same document:
verification §"Warp does not guarantee wl_keyboard.enter" predicted
`focuswindow` was "likely mandatory". It was not; the second warp
was.
Written down rather than smoothed over: the `focuswindow` branch
itself has no test, and if both mechanisms fail acquire still
returns ok with `focus="none"` -- a lease whose first key may go to
the previously focused window.
(D) The tap docstring claimed the `up` is sent even if the `down` was
refused after sending. The next lines return early on `not ok`, and
that early return is right: a refusal means the key was never
pressed, so an `up` would ask the compositor to release something it
never had. Sentence replaced with why the early return is correct
and what actually covers a lost reply (the broker's `release_all`,
not the CLI, which cannot know whether the request arrived).
Not done, and not claimed: findings 4, 6 and 7 (the broker chord test
checking first/last mask rather than the key; the at-cap test not
looking at the sink; the module-defaults test being a substring match).
The review rates all three as not holes in the claim, and the driver
tests are the locks for the first two.
nix develop -c python -m pytest tests -q
907 passed in 67.71s
nix develop -c python -m pytest tests/pointer tests/sessions/unit -q
605 passed in 27.16s
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GhNPM6rGcuzxocM1nATnuM
This commit is contained in:
1 parent
54dd109dde
commit
561e0c28f5
5 files changed
+321
-15
No files matched your search
@@ -0,0 +1,178 @@
|
||||
# Stage 2 and Stage 3 review — the broker learns to type, and the VM has to show it
|
||||
|
||||
Reviewed `e6f4c3b` (Stage 1 review fixes plus the broker, CLI and module), `7890315` (xkbcommon in the unit check, and the two-warp acquire tests), `a6a4094` (`checks/vm-keyboard.nix`, the keyboard victim, the helper derivation) and `54dd109` (the change to `checks/vm-pointer.nix`). Tip is `54dd109` on `feat/keyboard-input`. Line numbers below are that tip, not the individual commits.
|
||||
|
||||
Nothing was rebuilt. Pytest was not run. The VM checks were not run — they are slow and are being run elsewhere. What follows is a reading of the code and of what each assertion would and would not catch. A green VM log from another machine is not evidence this review produced.
|
||||
|
||||
The Stage 1 fixes that `e6f4c3b` claimed are in the tree and are not re-opened here. `key` of a capital sends the mask before the key (`tests/pointer/test_ops.py:510-528`). `type` under a held Control asserts the whole sequence, including the key, and the comment says why a first-and-last check would pass while typing nothing (`test_ops.py:653-688`). `release_pressed_on_close = true` is set (`nix/hyprland-conf.nix:134-136`). The keymap upload is ordered connect, upload, listen, serve (`tests/pointer/test_driver_flags.py:254-272`) and the payload test counts the NUL (`test_driver_flags.py:286`). A key-up forgets the name only after the sink accepts (`test_ops.py:589`). `checks/unit.nix:27` puts `xkbcommon` next to `pywayland`, so the resolver tests cannot skip.
|
||||
|
||||
---
|
||||
|
||||
## Stage 2 — broker, CLI, module
|
||||
|
||||
### Verdict
|
||||
|
||||
**done-with-fixes.** The verbs, the exit codes, the driver token, the two warps, the layout argv and the audit count are implemented and the tests that exist mostly look at the bytes the driver would send. Two tests the verification named as false passes were not written. The behaviour they would lock is the shared cache and a call that is already in `kill()`. Fixing them is two tests, not a redesign.
|
||||
|
||||
### What is in the tree
|
||||
|
||||
**Verbs.** `keyboard.key` and `keyboard.type` are in `VERBS` and in `MUTATING_VERBS` (`src/hhstreamd/protocol.py:157-188`). There is no `keyboard.acquire`. Both go through `_refresh` (`manager.py:1882`, `1913`), so they refresh the lease and do not mark activity. `test_typing_does_not_count_as_activity` (`tests/sessions/unit/test_keyboard_verbs.py:523-543`) asserts the timestamp **and** `command_count`. `pointer.state` reports `keys` as names (`manager.py:1849-1851`). `pointer.release` reports `keys_lifted` beside `buttons_lifted` (`manager.py:1822-1837`). Expiry reads `keys_pressed()` before `expire()` and then one `release_all` (`manager.py:1962-1975`).
|
||||
|
||||
**Exit codes, and they are the ones the plan names.**
|
||||
|
||||
| Code | Name | How it is reached |
|
||||
| --- | --- | --- |
|
||||
| 2 | `invalid_argument` | Bad state, non-string text, over the scalar cap, at the broker before the driver (`manager.py:1884-1922`). A bad keysym or an unmappable character, after the driver says `kind`. |
|
||||
| 8 | `pointer_busy` | A second `pointer.acquire` only (`manager.py:1628-1635`). Holding a key does not change that. `test_a_second_acquire_while_a_key_is_held_is_busy_and_leaves_the_key` (`test_keyboard_verbs.py:171-185`) checks the holder and the key both survive. |
|
||||
| 9 | `no_lease` | No lease, or another session's lease id (`test_keyboard_verbs.py:144-168`). Not 8. The CLI prints the exit-9 sentence (`src/hhstream_session/format.py:399-404`, `KEYBOARD_LEASE_NOTE` at `__init__.py:491-498`). |
|
||||
| 10 | `driver_refused` | Anything the driver refuses without `kind == "invalid_argument"`, including a missing keyboard global (`manager.py:2168-2177`, `test_keyboard_verbs.py:387-407`). Pointer move still works in that test. |
|
||||
|
||||
**The token mapping landed.** The driver sets `kind` to `invalid_argument` for a bad keysym, a bad state, an unmappable character and an over-cap string (`src/hhstream_pointer/ops.py:107-117`, `457-466`). The client copies `reply["kind"]` onto `DriverRejected` (`src/hhstreamd/driver.py:218-221`). `_drive` maps that one token to `ManagerError("invalid_argument")` and leaves every other refusal, including a missing `kind`, as `driver_refused` (`manager.py:2168-2177`). `test_an_unmappable_character_is_exit_2_and_types_nothing` (`test_keyboard_verbs.py:288-304`) goes through the real manager, the real UNIX socket and the real dispatcher on a compiled `us` keymap (`tests/sessions/fakes.py:477-493`). It asserts the error name, `exit_code_for == USAGE`, and `sink.calls == []`. A driver that refused `é` as `driver_refused` fails it. A driver that typed `caf` and then refused fails it. This is not a fake that returns the error name by agreement.
|
||||
|
||||
**Two warps, and the threshold is pinned.** `pointer_acquire` always calls `_warp_taking_focus` (`manager.py:1638-1639`). That sends a warp to `(x, _nudged(y))` and then a warp to `(x, y)` (`manager.py:2220-2234`). `FOCUS_NUDGE` is `0.004` (`manager.py:2392`), about 2.88 px at the frozen 1280×720 mode, so the floored pixels differ. The unit test asserts two warps, the second equal to the bookmark, the rounded pixels different, and `focus == "warp"` (`test_keyboard_verbs.py:624-651`). The integration test pins the nudge itself: after a restore to `(0.8, 0.2)` the sink saw `(0.8, 0.204)` then `(0.8, 0.2)` (`tests/sessions/integration/test_containers.py:580-585`). `follow_mouse = 1` and `follow_mouse_threshold = 0` are written out in `nix/hyprland-conf.nix:99-115`, not inherited. The comment says why raising the threshold stops acquire taking the keyboard.
|
||||
|
||||
**The fallback is not where the plan's stage table puts it.** See finding 3. The second motion is real. The `focuswindow` call exists, on nudge failure only, and the contract describes that. The plan's stage table still says it is Stage 4.
|
||||
|
||||
**CLI and module.** `hhstream session keyboard type|key|down|up` is built in `_build_keyboard` (`src/hhstream_session/__init__.py:501-627`). Each verb takes `--lease` and otherwise reuses the cached pointer lease, and refuses with `_no_lease` (exit 9) when there is none (`__init__.py:1232-1296`). `type` renders a character count, never the text (`__init__.py:1241-1248`). `sessions.keyboard.layout` is `strMatching "[A-Za-z0-9_-]+"`, default `"us"` (`nix/module.nix:630-638`). The only consumer is `hhstream-pointer`'s `ExecStart`, as `--xkb-layout` and the three sibling flags (`nix/module.nix:1060-1080`). There is no `[keyboard]` TOML table. The audit event is `chars=len(text)` (`manager.py:1927`). The generic `request` audit stores the verb, the error name and the request id, not the body (`server.py:233-242`). Driver refusals name a scalar index and a `U+` codepoint (`test_keyboard_verbs.py:307-317`). A non-string `text` can put `text!r` into an error reason (`manager.py:1915`); that is a shape check, not a typed string. Nothing in the broker, the CLI render or the audit line logs the text. The shell's own argv is out of scope, and the plan says so.
|
||||
|
||||
### Findings
|
||||
|
||||
Ordered by what they cost to fix. None of them is a missing verb.
|
||||
|
||||
1. **The replay test asserts set membership, not the sink.** The verification's own false pass (`docs/plans/2026-10-04-keyboard-verification.md` §B2): "Asserting `deduplicated` and not the sink. A handler that types and then sets the flag stays green." What landed is `test_every_keyboard_verb_is_cached_for_the_same_reason` (`tests/sessions/unit/test_broker_protocol.py:175-184`), which checks that the two names are in `MUTATING_VERBS`. The cache itself is real and is not keyboard-specific: `_dispatch` looks up `request_id` before the handler and `remember`s after (`server.py:196-231`), and the key is the request id alone (`protocol.py:196-222`). `test_a_retried_click_with_the_same_request_id_clicks_once` (`test_containers.py:545-561`) is the shape the spec asked to copy, and it counts `sink.of("button")`. Nothing replays `keyboard.type`, and nothing replays an unmappable `type` and asserts the sink stayed empty. The CLI does not send a `request_id` on keyboard verbs (same as the pointer gestures; `--request-id` is on start/kill/gc/adopt/reconcile). Dedup only fires when a caller of the broker socket supplies one. A regression that removed the two names from the set fails the membership test. A regression that typed and then cached would not, because that test never calls the handler.
|
||||
|
||||
Cheapest fix: copy the click integration test. One `keyboard.type` of `"ab"` with `request_id="retry-me"`, a second call with the same id, assert `deduplicated` and that the sink's `key` count did not grow. A second case, an unmappable string, same id twice, sink still empty.
|
||||
|
||||
2. **Key-lift on kill is tested by calling the helper, not `kill()`.** `test_killing_the_holder_lifts_its_keys` (`test_keyboard_verbs.py:563-574`) calls `manager._drop_lease_for(..., "kill")` and then looks for the key-up on the sink. `SessionManager.kill` does call `_drop_lease_for(session, reason="kill")` (`manager.py:1232-1237`), so the production path is there. The spec named the false pass: a `kill` of a session that does not hold the lease, or a `kill` that no longer calls the helper, stays green. The existing integration kill test (`test_containers.py:520-529`) asserts `dispatcher._pressed == {}` and a null holder. It never holds a key, so removing the call from `kill()` while leaving `_drop_lease_for` itself correct stays green.
|
||||
|
||||
Cheapest fix: in that integration test, `keyboard.key` down of `Shift_L` before `kill`, then assert the sink lifted it (or `pointer.state` `keys == []` after, which is weaker — prefer the sink).
|
||||
|
||||
3. **`focuswindow` is inside acquire, on nudge failure, and the plan still says it is Stage 4.** The code matches `docs/CONTRACT-sessions.md` v3 (`:407-413`): two warps, reply field `focus` of `warp` / `focuswindow` / `none`, depending on a threshold the conf file sets. It does not match the plan. The risk paragraph still says acquire is one warp and the fallback "is still not built in Stages 1–2", on `window.stable_id`, immediately before the first key (`docs/plans/2026-10-03-keyboard-input.md:297`, stage table at `:324`).
|
||||
|
||||
What the code actually does (`manager.py:2220-2260`): if the nudge warp raises, log it, call `hyprctl dispatch focuswindow` with `address:` from `session.container.window.address` or else `pid:{session.pid}`, then **still send the target warp**. The target warp's failure still drops the lease (`manager.py:1640-1644`). `address:` is the selector `vm-pointer` itself uses and treats as working (`checks/vm-pointer.nix:493-494`). `pid:` is the branch when no address has been read back, and nothing tests it. `stable_id` would be the wrong selector; the code is more correct than the plan's wording.
|
||||
|
||||
The fallback does not cover the failure Stage 0 measured. That failure is "both warps were sent and the keyboard did not move", which is what the second warp is for, and only when the threshold is 0. The fallback covers a driver error on the nudge. A driver that is down fails the target warp too and the acquire aborts, so the path that returns `focuswindow` is the narrow one where the nudge fails and the target warp succeeds. Nothing tests it. `test_acquire_sends_two_motions_so_keyboard_focus_moves` requires `focus == "warp"`. The VM does the same (`checks/vm-keyboard.nix:511-515`), so a broken fallback stays green everywhere. If both mechanisms fail, acquire still succeeds and reports `focus="none"` (`manager.py:2233`). That is a lease whose first key goes to the previously focused window. The VM would catch it. No unit test does.
|
||||
|
||||
Cheapest fix: edit the plan. Strike stage 4's "build `focuswindow` before the first key", and rewrite the risk paragraph so it describes the two warps and the nudge-failure fallback the contract already describes. Do not move the call to match the stale paragraph. A test that forces the nudge to raise and asserts one `focuswindow` plus the target warp is worth having; it is not what makes the two-warp true.
|
||||
|
||||
4. **The broker chord test checks the first and last mask, not the key.** `test_a_held_modifier_survives_a_type_and_ors_into_it` (`test_keyboard_verbs.py:231-245`) asserts `calls[0]` and `calls[-1]` are the Control mask and that the lease still holds `Control_L`. It does not assert a `key` event for `c` between them. The comment on the driver test (`test_ops.py:680-682`) says that shape types nothing and stays green. The driver test is the real lock: the whole sequence, including the key (`test_ops.py:662-668`). The broker test is a weaker copy. Not a functional bug.
|
||||
|
||||
Cheapest fix: assert the four-tuple the driver test already asserts, against `harness.fake.sink.calls`.
|
||||
|
||||
5. **The tap's comment describes a behaviour the code does not have.** `_cmd_keyboard_key` says the up is sent even if the down was refused after sending (`src/hhstream_session/__init__.py:1257-1260`). The next lines return immediately when `down` is not `ok` (`:1269-1270`). A broker refusal (bad keysym, never pressed) should not send the up, and the early return is right for that. A reply lost after a successful down is a connection error, not `ok: false`, so the sentence is not implemented and should not be. Cheapest fix: delete the sentence.
|
||||
|
||||
6. **`test_exactly_the_cap_is_accepted` does not look at the sink** (`test_keyboard_verbs.py:366-373`). It asserts `reply["chars"]`. A handler that returned the count and never called the driver stays green. The over-cap test does assert `sink.calls == []`. Cheapest fix: assert the sink is non-empty, or at least that its length is `2 * MAX_TYPE_SCALARS` key events. Low; the dispatcher has its own cap tests.
|
||||
|
||||
7. **`test_the_module_passes_the_same_defaults_this_binary_has` is a substring of `nix/module.nix`** (`test_driver_flags.py:160-174`). `default = "us"` in a comment, or `"--xkb-layout"` anywhere in the file, satisfies it. The VM's `ExecStart` assertion is the one that would notice (`checks/vm-keyboard.nix:386-392`). Not worth a new unit test if Stage 3 stays.
|
||||
|
||||
### What the merge request must not claim
|
||||
|
||||
- That a replayed `keyboard.type` was shown not to type twice. Membership in `MUTATING_VERBS` was shown. The click replay test covers the cache for clicks.
|
||||
- That `kill()` was shown to lift keys. `_drop_lease_for` was shown to. `kill()` contains the call; no test goes through it with a key down.
|
||||
- That `focuswindow` is tested, or that it is the Stage 0 fix. The Stage 0 fix is the second warp. The fallback runs when the nudge cannot be sent, returns `focus="none"` without failing the acquire when the compositor call also fails, and no test enters that branch.
|
||||
- That the plan's stage table was followed. The contract was. The plan still says Stage 4.
|
||||
- That Wayland bytes were inspected. Broker tests see `RecordingSink` tuples from the real dispatcher. One test calls the real `upload_keymap` for the NUL size. That is the right layer for a unit test and it is not a compositor.
|
||||
|
||||
### Carried objections
|
||||
|
||||
- The plan's stage table and risk paragraph disagree with `CONTRACT-sessions.md` v3 and with the code. Fix the plan, or say in the merge request that the contract wins. Do not treat it as unfinished Stage 4 work.
|
||||
- Keyboard CLI verbs do not generate `request_id`. Same as pointer gestures. Dedup is for a caller of the control socket.
|
||||
- `ps` of the CLI's `type` argument shows the string. The plan excludes it. `events.jsonl` does not contain it, on the path the unit test checks (the `keyboard_type` event only; the VM greps the whole file).
|
||||
- Every acquire moves the cursor by about 3 px and back. Clients see both warps. That is the mechanism, not an accident. `vm-pointer`'s repaired subtest prints the jiggle.
|
||||
- No `[keyboard]` table. Layout is argv only. Hyprland `input:kb_layout` is not read. Both are what change 5 of the verification asked for.
|
||||
- The unit pixel check uses `round(y * 720)` (`test_keyboard_verbs.py:650`). Hyprland floors. At `0.004` both differ (2.88 px). A future nudge under one pixel could pass `round` and fail `floor`, or the reverse. The integration assertion of `0.204` is the one that pins the constant.
|
||||
|
||||
---
|
||||
|
||||
## Stage 3 — the VM check
|
||||
|
||||
### Verdict
|
||||
|
||||
**done.** Read as a check, not as a log this review produced: two windows, characters on one and silence on the other, a key-up after a real TTL, a second acquire refused, and the symbol taken from the keymap the compositor forwarded. `vm-keyboard-de` is a second run of the same script with `sessions.keyboard.layout = "de"`, and a hardcoded `us` fails it in more than one place. The `vm-pointer` edit repairs a premise the two-warp broke. The helper is on the path the check executes, and a missing binary fails the check rather than falling back. `vm-keyboard` and `vm-keyboard-de` would not pass on `main`. This review did not run them.
|
||||
|
||||
### Does the check prove the claim?
|
||||
|
||||
The victim compiles the fd from `wl_keyboard.keymap` with xkbcommon and decodes with that state (`checks/lib/keyboard_target.py:177-215`). No keymap, or one that will not compile, is printed as `UNREADABLE` / `WILL-NOT-COMPILE` / `sym=?`, not as a guessed character. The wrapper is `exec ${tools}/bin/hhs-keyboard-target` with no other program (`checks/vm-keyboard.nix:146-148`). Hyprland `input:kb_layout` is left at its default in both runs (`extraConfig` is empty on this machine; `session-machine.nix:55-57` only appends what the check passes). The header of `vm-keyboard.nix` (`:52-80`) records the two places the written spec is now wrong, and the assertions match that header rather than the stale sentences.
|
||||
|
||||
What a false green would look like, and what the check does instead:
|
||||
|
||||
| Claim | A false green | What is asserted |
|
||||
| --- | --- | --- |
|
||||
| Two windows, B focused first | One session, or A's map-time `keyboard enter` counted as the acquire. | `beta` is started second. `focusHistoryID == 0` must be beta's output **before** acquire (`vm-keyboard.nix:457-475`), and beta must already have `keyboard enter` (`:478-482`). The acquire subtest snapshots pointer-enter, keyboard-enter on alpha and keyboard-leave on beta **before** the acquire (`:504-506`) and waits for new ones (`:517-535`). |
|
||||
| Acquire took the keyboard, not only the cursor | `pointer enter` on alpha, beta still has the keys, `focus` unchecked. That is what one warp does. | `reply["focus"] == "warp"` (`:511-515`). New pointer enter **and** keyboard enter on alpha, keyboard leave on beta (`:517-535`). `focuswindow` or `none` fails the reply assert, so this check does not accept the fallback as success. |
|
||||
| `hello` on the holder | The log is searched for the substring `hello`, which a script that echoes its argv would satisfy. Or keycodes with no symbol, counted as success. | `typed()` is `sym=` from `keyboard key` lines only (`:241-249`, `:288`). The holder must decode `["h","e","l","l","o"]` (`:627-631`). Any `sym=?` fails (`:632-634`). |
|
||||
| Silence on the other | Beta never bound a keyboard, so it is silent even when focus never moved. Or beta's key lines scrolled out of the log window (below). | The same subtest requires beta's new key lines to be `[]` (`:619-626`) **and** the positive decode above. Beta bound a keyboard in the focus subtest. The two are one subtest on purpose (`:603-606`). |
|
||||
| Capital A is a mask | Some non-zero mask anywhere in the log, or a Shift keycode the client ignored. | Press and release are both `sym=A` (`:568-572`), no keycode 42 in the pair (`:573-575`), some mask in the span is non-zero, and the span ends at 0 (`:590-598`). `sym=A` is the ordering proof: the client decodes with the mask it had been given when the key arrived. The comment explains why `span[0]` would flake on the focus-change `modifiers depressed=0`. |
|
||||
| Key-up after a real TTL | A `state=0` left over from `hello` (those are code 30 and others, not 42). Or an injected clock, which the unit suite already has. | `--ttl` of 8 seconds, `keyboard down Shift_L`, then `wait_until_succeeds` until `pointer state` has a null holder (`:862-889`). The client must report code 42 down then up (`:897-915`) and the mask span must end at 0 (`:916-923`). `type` is not allowed to emit 42, which is why Shift is the key. |
|
||||
| Second acquire refused | A leftover holder from an earlier subtest, so any acquire of beta exits 8. | This subtest holds `Shift_L` on alpha, **then** has beta acquire (`:807-827`). Exit 8, the holder is still alpha, and `keys` is still `["Shift_L"]`. |
|
||||
| Symbol from the compositor's keymap | The victim compiled its own `us` table and decoded `hello` from either layout. | `keymap_new_from_string` on the forwarded text (`keyboard_target.py:198`). Exactly one `keyboard keymap` line, not `UNREADABLE`, not `WILL-NOT-COMPILE`, `symbols=` matching the layout (`vm-keyboard.nix:415-438`), and that line's position is before any `keyboard key` line (`:445-452`). |
|
||||
|
||||
Residual, not a false green of the happy path: `target_log` asks for `--lines 800` (`vm-keyboard.nix:229`). `keys(beta)[before:]` is a slice of that tail. If beta's older key lines scroll out of the window, the saved index lands past the new tail and the silence slice is `[]` while beta did receive keys. The `hello` subtest is early, and beta has almost no key lines yet, so this is unlikely there. It is a real hole in the negative assertion if a later edit moves the silence check down the script. A false **red** of the same shape (the positive slice starts in the middle of the new events) is the more likely failure if the window is hit.
|
||||
|
||||
`format=1` (`vm-keyboard.nix:431-433`) is the format the **client** was given. Hyprland can ignore the format on the virtual-keyboard request and always forward format 1. The check does not prove we uploaded format 1. The unit test of `upload_keymap` is the one that sees the request we sent.
|
||||
|
||||
### Does `vm-keyboard-de` exercise a non-`us` layout end to end?
|
||||
|
||||
Yes, as written. `checks/default.nix:66-68` calls the same file with `keyboardLayout = "de"`. `session-machine.nix:87-91` sets `sessions.keyboard.layout` from that argument, which is the option the module puts on `ExecStart`. The `de` run then requires all of:
|
||||
|
||||
- `--xkb-layout de` on the unit (`vm-keyboard.nix:390-392`);
|
||||
- forwarded symbols `pc_de_inet(evdev)` (`:161-167`, `:434-438`);
|
||||
- `type y` arriving as evdev 44 and `type z` as 21, with the sym still `y` and `z` (`:662-692`);
|
||||
- `type cafü` succeeding, `chars == 4`, decoded as `c,a,f,udiaeresis` (`:710-727`).
|
||||
|
||||
A hardcoded `us` fails the symbols line, fails y's code (21 ≠ 44), fails `ü` (exit 2, and the refusal must name `scalar 3` and `U+00FC` without quoting the string, `:728-761`), and fails the argv check. The argv check alone is the false pass the spec named ("greps the unit for `--xkb-layout de` and never types `y`"). It is not the only assertion. Leaving `input:kb_layout` at `us` is what makes a client that ignored our keymap decode the `us` answer on the `de` run.
|
||||
|
||||
The spec's "`type y` on `de` decodes to sym `z`" (`docs/plans/2026-10-04-keyboard-verification.md` §B3 subtest 4) contradicts the same section's rule that the victim decodes the forwarded keymap. A correct driver sends `de`'s code for keysym `y`; the client, using that keymap, reads `y` back. The check documents this (`vm-keyboard.nix:52-69`) and asserts the code, the symbols name and whether `ü` is typeable. That is the right reading. Do not "fix" the check to expect `z`.
|
||||
|
||||
### Was `vm-pointer` repaired or weakened?
|
||||
|
||||
**Repaired.** `54dd109` does not drop the property. It changes how the situation is arranged.
|
||||
|
||||
The property is: a warp is delivered to the session it was aimed at, and the window that holds keyboard focus is told nothing (`checks/vm-pointer.nix:449-462`). That is `input:follow_mouse`, not keyboard focus. It used to be free, because one warp did not move keyboard focus, so after acquire the other session was still focused. Two-warp acquire focuses the holder, so the old precondition ("the other window is focused") stopped arranging itself. The new code acquires, asserts the bookmark is still `(0.25, 0.75)` (`:482-485`), then `hyprctl dispatch focuswindow address:…` on the **other** session as setup (`:493-506`), asserts that window is the focused one, then `pointer move` to `(0.6, 0.4)`. The focused client's events since that setup must be empty (`:529-534`). The aimed client's last reported position must be near the aim (`:535-537`).
|
||||
|
||||
`before` is taken before the acquire (`:479`), so `mine` includes the two acquire warps. `mine[-1]` against `(0.6, 0.4)` still requires the later move: the acquire restores `(0.25, 0.75)`, which is not close to the aim. `before_other` is taken after the focus command and before the move (`:511`), so the focused client's slice does not include anything from the acquire.
|
||||
|
||||
The commit message says `nix build .#checks.x86_64-linux.vm-pointer` passed, 12/12. This review did not reproduce that.
|
||||
|
||||
One residual flake, and it is a false **red**, not a false green. `wait_for` returns when **either** client has new events (`:519-523`). The aimed client already has the acquire warps in `positions(session_id)[before:]`, so the wait can return before the move is logged. `mine[-1]` is then the bookmark, the closeness assert fails, and the check goes red. It does not go green.
|
||||
|
||||
This check would still pass on `main`. On `main`, acquire does not take keyboard focus, the other session is already focused, and the extra `focuswindow` is a no-op setup of a situation that already holds. The routing property predates the keyboard. That is correct. It is not a keyboard check, and a green `vm-pointer` on `main` says nothing about this feature.
|
||||
|
||||
### The helper
|
||||
|
||||
`checks/lib/session-tools.nix` builds `hhs-ipc-watch`, `hhs-pointer-target` and `hhs-keyboard-target`. The keyboard one is installed from `keyboard_target.py` and its shebang is rewritten to a Python with pywayland and xkbcommon (`:76-78`). The builder then `test -x`s all three and runs `--help` (`:84-89`), and compiles a real `us` keymap in that interpreter (`:95`). The comment at the top (`:14-35`) describes the old failure: an indented heredoc terminator swallowed the rest of the builder, the derivation still built, and `$out/bin` contained only `hhs-ipc-watch`. The self-tests had become text inside the shim, so they never ran. `writeTextFile` plus those `test -x` lines is what makes that failure a build failure now.
|
||||
|
||||
The check uses that binary. `tools` is `session-tools.nix` (`vm-keyboard.nix:127`), the guest wrapper execs `${tools}/bin/hhs-keyboard-target` (`:146-148`), and the first subtest that needs a window fails if the target exits 127 (`:397-413`). There is no `||` and no foot fallback. Nix interpolation of the path depends on the derivation; it does not by itself notice a missing file inside `$out`. The derivation's own `test -x` does, and the check depends on the derivation, so a helper that was not installed fails the check's build. A runtime absence (self-test removed, file deleted after the build) fails in the guest as exit 127, which the "victim never got a window" subtest turns red. Same `tools` output supplies `hhs-pointer-target` to `vm-pointer` and `vm-containers`; those checks fail the same way if the pointer target is absent. The keyboard target is not optional on the keyboard check.
|
||||
|
||||
### Would any of this pass on `main`?
|
||||
|
||||
`vm-keyboard` and `vm-keyboard-de` would not. `main` has no `keyboard` CLI, no virtual keyboard on the seat (the headless seat has no keyboard capability, and "target: keyboard bound" is the subtest that requires one), no keymap upload, and an acquire that is one warp, so the keyboard-enter half of the acquire subtest fails. `vm-pointer` would. See above. That split is what "load-bearing" means here: the new checks go red without the feature, and the old check still measures the property it measured before.
|
||||
|
||||
### Findings
|
||||
|
||||
None that change the verdict. Two are worth fixing if the file is touched, and neither is a hole in the claim above.
|
||||
|
||||
1. **The chord subtest does not look at the character.** `vm-keyboard.nix:766-805` holds `Control_L`, types `c`, waits until two key events have arrived, and asserts `pointer state` still lists `Control_L`. It never asserts the sym or the code. Two key events of anything, with Control still held, pass. The driver test is the lock (`test_ops.py:653-668`). Cheapest fix: assert the pair decodes to `c`, `c`. The spec's B3 list does not include this subtest; it is extra. Not a reason to call the stage open.
|
||||
|
||||
2. **`wait_for` in the repaired `vm-pointer` subtest can return on the acquire warps.** False red, described above (`vm-pointer.nix:479`, `:519-523`). Cheapest fix: take `before` after the acquire, or wait until `mine[-1]` is near the aim. Do not "fix" it by dropping the closeness assert.
|
||||
|
||||
### What the merge request must not claim
|
||||
|
||||
- That §B3's "`type y` on `de` decodes to sym `z`" was implemented. It was not, correctly. The proof is the evdev code, the symbols name `pc_de_inet(evdev)`, and that `ü` is typeable on `de` and exit 2 on `us`.
|
||||
- That this review ran `vm-keyboard` or `vm-keyboard-de`. It did not. The `vm-pointer` re-run claimed in `54dd109` was not reproduced here either.
|
||||
- That `format=1` in the client log proves the driver uploaded format 1.
|
||||
- That the `focuswindow` fallback was exercised. The check requires `focus == "warp"` and treats the other two values as failure.
|
||||
- That `vm-pointer` going green is evidence of the keyboard. It is evidence the cursor still goes to the window under it. It would go green on `main`.
|
||||
- That a silence assertion is safe at any point in a long script. It is a slice of an 800-line tail.
|
||||
|
||||
### Carried objections
|
||||
|
||||
- The plan's Stage 3 gate still says "do not design the enter subtest from acquire's single warp" (`2026-10-03-keyboard-input.md:323`) and the verification still says one warp (`2026-10-04-keyboard-verification.md` §B3 subtest 1). The check's header is the text that matches the code. Same docs drift as Stage 2 finding 3; one edit covers both.
|
||||
- The chord subtest, as finding 1. Leaving it does not weaken `hello`, the capital, or the layout run.
|
||||
- The 800-line tail, as above. Fine for this script's early silence check. Do not copy the pattern into a later subtest without counting lines.
|
||||
|
||||
---
|
||||
|
||||
## One line
|
||||
|
||||
After the two tests in Stage 2 findings 1 and 2, this branch is safe to merge; update the plan's stage table so it matches the contract (or say in the merge request that the contract wins), and nothing else has to happen first.
|
||||
Reference in new issue
Block a user