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
@@ -21,12 +21,18 @@
|
||||
> | 7 | Stage 0's expectations, and `keyboard down` warns unconditionally |
|
||||
> | 8 | Acquire's stderr mentions keyboard verbs; refusals carry a scalar index, never the string |
|
||||
>
|
||||
> **Stage 0 has run** (`tests/README-keyboard-probe.md`, with its transcript).
|
||||
> The three open behavioural questions are answered, and one answer is worse
|
||||
> than this document assumes: **a single idle warp does not move keyboard
|
||||
> focus**, so `pointer acquire` — which is one warp — can leave the first key
|
||||
> of a lease going to whatever was already focused. §6 risk 1 still holds and
|
||||
> the fallback is still not built in Stages 1–2.
|
||||
> **Stage 0 has run** (`tests/README-keyboard-probe.md`, with its transcript),
|
||||
> and Stages 1–3 are built. The three open behavioural questions are answered,
|
||||
> and one answer was worse than this document assumed: **a single idle warp
|
||||
> does not move keyboard focus.** That is resolved rather than outstanding —
|
||||
> `pointer acquire` now sends **two** warps a real pixel apart, and
|
||||
> `nix/hyprland-conf.nix` pins the `follow_mouse_threshold` the second one
|
||||
> depends on. See §6 risk 1, which is rewritten, and the Stage 3/4 rows, which
|
||||
> are not pending work.
|
||||
>
|
||||
> **Where this file and `docs/CONTRACT-sessions.md` v3 disagree, the contract
|
||||
> wins.** It describes what shipped; several paragraphs here describe what was
|
||||
> planned before Stage 0 measured the compositor.
|
||||
|
||||
Typing stops being a non-goal. `docs/PLAN-workspaces-and-pointer.md` §1 defers it, and §6.7 already specifies the shape: same seat, same serialisation, `zwp_virtual_keyboard_manager_v1`, and the existing pointer lease rather than a new lock. Stages 0–3 of that plan are what the tree implements today (broker lease in `src/hhstreamd/pointer.py`, driver in `src/hhstream_pointer/`, CLI in `src/hhstream_session/__init__.py`). This plan is §6.7, with one correction noted under lease semantics.
|
||||
|
||||
@@ -279,7 +285,7 @@ Match the split already in the tree: the dispatcher is tested against a recordin
|
||||
|
||||
- Victim: a small Wayland client beside `checks/lib/pointer_target.py` (or an extension of it) that sets `xdg_toplevel` app id from `$HHSTREAM_APP_ID` and prints `wl_keyboard.enter`, each `key` (evdev code, state), each `modifiers` mask, and the keysym it decodes from the keymap the compositor forwarded. Read-back is `hhstream session logs`, as in `vm-pointer`.
|
||||
- Assertions, real time, no injected clock (the unit clock already covers the arithmetic; `vm-pointer`'s expiry subtest states why):
|
||||
1. After `pointer acquire` on session A, A's log shows `wl_keyboard.enter`. This is the focus measurement. If it fails, the check is red and Stage 4 is in play — do not weaken the assertion.
|
||||
1. After `pointer acquire` on session A, A's log shows `wl_keyboard.enter`. This is the focus measurement, and it is asserted against acquire itself: acquire is two warps (§6 risk 1), so this is a live assertion rather than one expected red. `checks/vm-keyboard.nix` also requires the reply's `focus == "warp"`, so the nudge-failure fallback is not accepted as success, and it asserts `wl_pointer.enter` separately — a check that saw only the cursor arrive would pass while the first keystroke went elsewhere. Do not weaken it.
|
||||
2. `keyboard type A hello` decodes to the characters `hello` on A and to nothing on session B.
|
||||
3. `keyboard down A Shift_L`, wait out a short `--ttl`, A's log shows the key-up and a cleared mask, and `pointer state` shows no holder.
|
||||
4. A second acquire during the hold exits 8.
|
||||
@@ -294,7 +300,16 @@ Match the split already in the tree: the dispatcher is tested against a recordin
|
||||
|
||||
- **Focus does not follow a single virtual-pointer warp. [MEASURED — Stage 0, and this is the headline risk of the feature.]** One `motion_absolute` onto an unfocused window, after the cursor had been still for 0.8 s, delivered `wl_pointer.enter` and **no** `wl_keyboard.enter`; the focus change arrived only after a *later* motion that changed the floored pixel. The mechanism is `InputManager::onMouseWarp` → `mouseMoveUnified(refocus=false)`: the delta is set to 0 when the previous movement was over 0.5 s ago, `mouseMoveUnified` returns early when the floored pixel did not change at all, and keyboard focus is that delta compared against `input:follow_mouse_threshold` (measured 0.0, unset). Transcript in `tests/README-keyboard-probe.md`.
|
||||
|
||||
**`pointer acquire` is one warp**, so the first key of a lease can land in whatever was already focused. The fallback is the one named below — `dispatch focuswindow` on the session's `window.stable_id`, immediately before the first key of a lease — and **it is still not built in Stages 1–2.** Two things that are *not* the fix: warping twice to the same bookmark (the same floored pixel returns early), and waiting longer after the warp (the first warp's settle window was 0.4 s and contained the pointer enter alone). Stage 3's enter subtest must not be written against acquire's single warp.
|
||||
**[RESOLVED in Stage 2 — `pointer acquire` is now two warps.]** This paragraph used to end "acquire is one warp, so the first key of a lease can land in whatever was already focused; the fallback is not built in Stages 1–2". Both halves are out of date, and `docs/CONTRACT-sessions.md` v3 §4 is the text that describes what shipped:
|
||||
|
||||
- `pointer_acquire` calls `_warp_taking_focus`, which warps to a neighbouring pixel and *then* to the target. The second motion carries a non-zero `m_mousePosDelta`, so it moves keyboard focus; the cursor finishes on the target, so the bookmark is unchanged. `FOCUS_NUDGE` is 0.004, about 2.88 px at the frozen 1280×720 mode, which is what makes the *floored* pixel differ.
|
||||
- This depends on `input:follow_mouse_threshold` being 0, so `nix/hyprland-conf.nix` now sets it **explicitly** rather than inheriting the default. Raise it and acquire stops taking the keyboard.
|
||||
- `dispatch focuswindow` **is** built, and it is not what this risk needed: it runs only when the *nudge* warp could not be sent, and it selects on `address:` from the read-back (falling back to `pid:`), never on `stable_id`, which is not a Hyprland selector. The target warp is still attempted afterwards and its failure still drops the lease. The acquire reply and the audit event carry `focus`: `warp`, `focuswindow`, or `none`.
|
||||
- Still *not* the fix, and worth keeping written down: warping twice to the same bookmark (the same floored pixel returns early, before the delta is touched) and waiting longer after one warp (the measured settle window was 0.4 s and contained the pointer enter alone).
|
||||
|
||||
Measured end to end by `checks/vm-keyboard.nix` on both layouts: with session B holding keyboard focus, acquire on A delivers `wl_pointer.enter` **and** `wl_keyboard.enter` to A and `wl_keyboard.leave` to B. That subtest requires `focus == "warp"`, so it does not accept the fallback as success.
|
||||
|
||||
What is **not** covered by a test: the `focuswindow` branch itself. A driver that is down fails the target warp too and the acquire aborts, so the branch is the narrow one where the nudge fails and the target warp succeeds. If both mechanisms fail, acquire still returns `ok` with `focus="none"` — a lease whose first key may go to the previously focused window.
|
||||
- **Destroy of the virtual keyboard leaves a key down inside Hyprland. [MEASURED — Stage 0.]** `destroy` with a key held, with a second virtual keyboard keeping the seat's capability up, delivered no key-up; `input:virtualkeyboard:release_pressed_on_close` is `0` and unset. Worse than "stuck": `InputManager::onKeyboardKey` drops a *press* whose code is already in the seat's `m_pressed`, so the next driver's press of that code is ignored and the key is **dead** until something sends a matching up. Our shutdown path sends key-ups first (`_lift_everything`); a `-9` skips it, which is why **[change 4]** `nix/hyprland-conf.nix` now sets `release_pressed_on_close = true`. That setting emits key-ups only and still never clears the modifier mask, so `release_all` keeps sending `modifiers(0, 0, 0, 0)` regardless. Still no retry loop the button path does not have.
|
||||
- **Auto-repeat is the client's, which does not make it harmless. [MEASURED — Stage 0.]** `press_count=1` over a 1.5 s hold, with `repeat_info rate=25 delay=600` published at bind time. So the flood is real and it is foot/GTK/Qt producing it from our one press, for as long as the key is down — up to the TTL (default 30 s). **[SUPERSEDED — change 7]** the help text for `down` therefore warns unconditionally; the old "if it does, the help text says so" is the false pass the review named. v1 has no repeat-rate control, and `zwp_virtual_keyboard_v1` has no `repeated` state to ask the compositor about. Chords (`Control_L` held across a `type`) remain the justified use of `down`.
|
||||
- **Mask versus Shift keycode.** §4's letter path can still be wrong for a toolkit that ignores `modifiers` and only shifts when it sees `KEY_LEFTSHIFT`. The VM victim must print both the mask and the decoded sym. Chromium is not the first victim (`vm-pointer` avoided it; it is expensive and the app-id rule in `README.dev.md` item 4 only binds clients that honour `$HHSTREAM_APP_ID`).
|
||||
@@ -307,7 +322,7 @@ Match the split already in the tree: the dispatcher is tested against a recordin
|
||||
Questions 1–4 are **closed by Stage 0** (`tests/README-keyboard-probe.md` and its transcript). Question 5 is answered by the operator.
|
||||
|
||||
1. ~~Stage 0 global name and version on the actual `/run/hypr-stream` socket.~~ **`zwp_virtual_keyboard_manager_v1` at version 1.** No `wp_virtual_keyboard_v1`. The gate holds.
|
||||
2. ~~Does acquire's warp produce `wl_keyboard.enter`?~~ **No — not from a single idle warp.** See risk 1 above; this is the one answer worse than the plan assumed.
|
||||
2. ~~Does acquire's warp produce `wl_keyboard.enter`?~~ **Not from a single idle warp — so acquire stopped being a single warp.** See risk 1 above. Measured again end to end by `vm-keyboard` on both layouts, where the two-warp acquire does deliver `enter` to the aimed window and `leave` to the one that held focus.
|
||||
3. ~~On destroy, does Hyprland release keys that were down?~~ **No.** See risk 2.
|
||||
4. ~~Does Hyprland auto-repeat those keys?~~ **Not on the wire; the client does.** See the auto-repeat risk.
|
||||
5. **Answered: `us`, and configurable.** The operator's decision is a NixOS option in the `hhstream` namespace, string, default `"us"`, documented in `README.dev.md` — reaching the keymap as `--xkb-layout` on the driver unit, per change 5.
|
||||
@@ -320,7 +335,7 @@ Questions 1–4 are **closed by Stage 0** (`tests/README-keyboard-probe.md` and
|
||||
| 0 | **Done.** `tests/keyboard_probe.py`, its README and its transcript. Two windows, not one; read-only `hyprctl` for the boxes; `(a1)` and `(a2)` measured separately; no `hyprctl dispatch`. | S | **Passed.** Named global is `zwp_virtual_keyboard_manager_v1` v1. |
|
||||
| 1 | Driver: vendor, `keymap.py`, ops, backend upload, `__main__` flags, pointer unit tests. Pointer still runs if the global is missing. | M, about 3–5 days | `pytest tests/pointer` green. `type` of an unmappable character emits no events. |
|
||||
| 2 | Broker mirror, verbs, CLI, module argv, session unit tests, contract doc amendments, stale `follow_mouse` comments. **No `policy.py` and no TOML table** (change 5). | M, about 2–4 days | `pytest tests/pointer tests/sessions/unit` green. Expiry test shows `release_all` lifting a held key. No new unit under `nix/module.nix`, and nothing there beyond argv. |
|
||||
| 3 | `vm-keyboard.nix` and the keyboard target client. **Do not design its enter subtest from acquire's single warp** — Stage 0 says that does not focus. | M, about 2–3 days | Characters on A, silence on B, key-up after a real TTL, second acquire is 8. Red if the keymap was not uploaded. |
|
||||
| 4 | **No longer contingent: Stage 0 showed no `enter` after a single idle warp.** `focuswindow` via the broker's existing compositor IPC, immediately before a lease's first key, then re-run Stage 3. Still not to be built in Stages 1–2. | S, about a day | The Stage 3 enter assertion goes green without loosening it. |
|
||||
| 3 | **Done.** `checks/vm-keyboard.nix` and `checks/lib/keyboard_target.py`, exposed twice (`vm-keyboard`, `vm-keyboard-de`) because the layout reaches the keymap only through the driver unit's argv. Its enter subtest **is** written against acquire, because acquire is two warps now — see the risk paragraph above and the file's own header. | M | **Passed**, both layouts: characters on A, silence on B, key-up after a real TTL, second acquire is 8, red if the keymap was not uploaded. |
|
||||
| ~~4~~ | **Does not exist as pending work.** It was "build `focuswindow` before the first key of a lease, if Stage 0 shows no enter". Stage 0 did show no enter after a *single* warp, and the answer was the second warp in `_warp_taking_focus`, not a focus dispatch — so the Stage 3 enter assertion is green without loosening it. `focuswindow` shipped in Stage 2 as the nudge-failure fallback *inside* acquire, which is a different mechanism for a different failure. Nothing here is outstanding. | — | — |
|
||||
|
||||
Rollback of Stages 1–2 is reverting the commit: old brokers never send `key`/`type`, and an old driver rejects unknown ops with `ok: false` (`ops.py` already answers unknown `op` instead of dropping the connection). No registry schema bump. Bookmarks stay as they are.
|
||||
@@ -161,6 +161,8 @@ Pointer focus is updated later in the same function with no threshold. That is w
|
||||
|
||||
A second warp inside 0.5 s adds a non-zero delta and can focus. Stage 0 has to measure **one idle warp** and **a second warp inside the window** separately. `dispatch focuswindow` stays the fallback the plan names, and it is likely mandatory, not a surprise Stage 4. Do not build it in Stage 1. Do not write Stage 3's enter assertion against one window.
|
||||
|
||||
**[AMENDED after Stage 2 — "likely mandatory" was the wrong prediction.]** Stage 0 measured exactly what this paragraph predicted, and the fix that shipped is the **second warp**, not the focus dispatch: `pointer_acquire` sends a nudge and then the target, which is the "second warp inside 0.5 s" above. `focuswindow` did ship, but as the narrow fallback for a nudge that could not be *sent*, inside acquire — not as the mechanism that moves focus. So Stage 4 is not pending work of any kind. See `docs/CONTRACT-sessions.md` v3 §4 and §B3 subtest 1 below.
|
||||
|
||||
### Destroy, expiry, `kill -9`
|
||||
|
||||
Three different paths.
|
||||
@@ -315,7 +317,9 @@ Victim: a sibling of `checks/lib/pointer_target.py`, not foot and not Chromium.
|
||||
|
||||
Subtests:
|
||||
|
||||
1. **Enter.** Two sessions, A and B, B started last so B is focused (the `vm-pointer` measurement that already bit them). `pointer acquire` on A, one warp. A's log shows `enter` for A's app id **after** the acquire, and B's log shows `leave`. If (a1) of Stage 0 was "no enter", this subtest is expected red until the double-warp or `focuswindow` fallback is in, and the assertion is not weakened to "cursor coordinates look right".
|
||||
1. **Enter.** Two sessions, A and B, B started last so B is focused (the `vm-pointer` measurement that already bit them). `pointer acquire` on A. A's log shows `enter` for A's app id **after** the acquire, and B's log shows `leave`. The assertion is not weakened to "cursor coordinates look right".
|
||||
|
||||
**[AMENDED after Stage 0 and Stage 2 — this said "one warp", and "expected red until the double-warp or `focuswindow` fallback is in".]** Stage 0's (a1) did measure "no enter", and the answer shipped in Stage 2: **acquire is two warps**, a real pixel apart, which is the double-warp this sentence anticipated. So this subtest is a live assertion, not an expected red. `focuswindow` also shipped, but it is *not* what makes this pass — it runs only when the nudge warp cannot be sent — so the check additionally requires the reply's `focus == "warp"` and treats `focuswindow` or `none` as failure. And it asserts `wl_pointer.enter` on A separately from `wl_keyboard.enter`: a check that saw only the cursor arrive would go green while A had the cursor, B had the keys, and the first keystroke of the lease went to B. `docs/CONTRACT-sessions.md` v3 §4 is the authority on the mechanism.
|
||||
2. **`keyboard type` of `A` then of `hello`.** A's log contains, in order, `modifiers depressed=1`, `key code=30 state=1 sym=A`, `key code=30 state=0`, `modifiers depressed=0`, and **no** `code=42` on that span; then five key downs decoding to `h,e,l,l,o`. B's log has no `key ` line from this span.
|
||||
3. **TTL.** `keyboard down Shift_L`, `--ttl` of a few seconds, wait it out in real time. A's log shows code 42 released and `modifiers depressed=0`. `pointer state` has `holder` null and `keys` empty. A second `pointer acquire` from B during the hold, before the wait, exits 8.
|
||||
4. **Layout.** Same VM expression with `sessions.keyboard.layout = "de"` (module argument, so the unit argv changes). Do **not** set Hyprland `input:kb_layout` (leave it unset / `us`). `keyboard type y` decodes to sym `z`; `keyboard type z` decodes to sym `y`. The keymap line from the fd contains the symbols name `de`.
|
||||
|
||||
Reference in new issue
Block a user