docs(seam): the seven consequences, restated and corrected, and the unverified list

Adds section 7 (the seven consequences of plan step 7, each with its supporting citations and a status: CONFIRMED, CORRECTED or TARGET; plus three findings the plan did not list: a batch/transaction scope, the workspace methods that exist only on KDE, and error-type differences) and section 8 (everything not confirmed, with how to confirm it on a Mac, a Windows guest or by reading). Verified against the citations of sections 2 to 6 on wip-main aa52fdc4d9e5. Not verified: see section 8.
This commit is contained in:
LGUG2Z committed 2026-10-31 01:37:53 -07:00
1 parent 2f8f839b4f
commit dcadd9aa84
1 file changed
+52 -2
+52 -2
View File
@@ -51,7 +51,7 @@ Conventions. "Rect" is the shared `komorebi_layouts::Rect`: `left`, `top` are th
| 7 | Close | `close(id)` `K/backend/mod.rs:382`; `K/kwin/mod.rs:980-982` | `Window::close` `W/window.rs:563-565` -> `close_window` posts `WM_CLOSE` `W/windows_api.rs:694-700` | `AdhocWindow::close(&AXUIElement)` presses the AX close button `M/window.rs:1444-1453`, called on the foreground element `M/process_command.rs:327-332` | All three are requests, not guarantees. macOS returns `Ok(())` when the window has no close button (`:1451`). macOS closes the **foreground element**, not a stored `Window`. |
| 8 | Alive check | `is_window(id)` (provided, `window(id).alive`) `K/backend/mod.rs:612-614`; a destroyed window stays queryable with `alive == false` for a while `:18-22` | `WindowsApi::is_window` (`IsWindow`) `W/windows_api.rs:1090`; the reaper polls it every 20 ms `W/reaper.rs:173-210` | `Window::is_valid` = `copy_attribute_names` returns something `M/window.rs:572-574` | KDE: table lookup, never waits. Windows: kernel call, no app involvement, polled without the WM lock (`W/reaper.rs:173-210`). macOS: an AX round trip to the owning app, only driven on mouse-up/key-up from the event tap (`M/input_event_listener.rs:79-82`, `M/reaper.rs:84-93`) and after failed AX writes (`M/reaper.rs:164-173`): macOS has no pollable "is this window gone". |
| 9 | Foreground window | `foreground_window() -> Option<u32>` `K/backend/mod.rs:248`; `K/kwin/mod.rs:818-820` | `WindowsApi::foreground_window() -> Result<isize>` `W/windows_api.rs:718-720` | `MacosApi::foreground_window_id() -> Option<u32>` `M/macos_api.rs:429-444`; `foreground_window() -> Option<AXUIElement>` `:446-456` | KDE: table. Windows: `GetForegroundWindow`; a null handle is an `Err`. macOS: AX system-wide -> focused application -> focused window, then `_AXUIElementGetWindow` (private, `M/accessibility/private.rs:12-16`); `None` whenever any AX step fails; sync IPC. |
| 10 | Window list | `windows() -> Vec<WindowInfo>` `K/backend/mod.rs:242`; `K/kwin/mod.rs:810-812` | `WindowsApi::load_workspace_information` `W/windows_api.rs:437`, `enum_windows` `:433` (callbacks `W/windows_callbacks.rs`) | `MacosApi::load_workspace_information` `M/macos_api.rs:312-374` over `CoreGraphicsApi::window_list_info` `M/core_graphics/mod.rs:126-133` | KDE returns every candidate window with all fields (`WindowInfo` `K/backend/mod.rs:63-91`). Windows and macOS only enumerate at startup and learn the rest from events. **macOS joins two worlds by title**: CG gives window ids and names, AX gives elements, and the match is `window_by_title` (`==` or `contains`) (`M/application.rs:195-208`, `M/macos_api.rs:346`). |
| 10 | Window list | `windows() -> Vec<WindowInfo>` `K/backend/mod.rs:242`; `K/kwin/mod.rs:810-812` | `WindowsApi::load_workspace_information` `W/windows_api.rs:437`, `enum_windows` `:433` (callbacks `W/windows_callbacks.rs`) | `MacosApi::load_workspace_information` `M/macos_api.rs:312-374` over `CoreGraphicsApi::window_list_info` `M/core_graphics/mod.rs:126-133` | KDE returns every candidate window with all fields (`WindowInfo` `K/backend/mod.rs:63-91`). Windows and macOS enumerate at start-up (Windows also has `alt_tab_windows`, `W/windows_api.rs:763-771`) and otherwise learn from events. **macOS joins two worlds by title**: CG gives window ids and names, AX gives elements, and the match is `window_by_title` (`==` or `contains`) (`M/application.rs:195-208`, `M/macos_api.rs:346`). |
| 11 | Monitors and work areas | `monitors() -> Result<Vec<MonitorInfo>>` `K/backend/mod.rs:255`; `K/kwin/mod.rs:830-836` | `WindowsApi::load_monitor_information` `W/windows_api.rs:292`, `monitor(hmonitor)` `:1126-1166` | `MacosApi::latest_monitor_information` `M/macos_api.rs:212-309`, `load_monitor_information` `:96`, `update_monitor_work_areas` `:182` | KDE: table, logical pixels, `Err` when empty (`:831-834`). Windows: `win32_display_data`, physical pixels (process is PerMonitorV2, `W/main.rs:223`, `W/windows_api.rs:1169-1172`), `id: isize` (`W/monitor.rs:33`). macOS: **live** query of `NSScreen`, CoreGraphics and IOKit (`:213-221`), main-thread only (`:213`), `id` is the `CGDirectDisplayID`; work area is `NSScreen.visibleFrame` flipped into Quartz coordinates (`:275-291`). |
| 12 | Monitor from point | `monitor_from_point(x, y)` (provided) `K/backend/mod.rs:622-628` | `WindowsApi::monitor_from_point` `W/windows_api.rs:492-496` | `CoreGraphicsApi::display_with_point` `M/core_graphics/mod.rs:102-123`, `MacosApi::monitor_from_point` `M/macos_api.rs:481-483` | KDE and macOS return `None` outside every monitor; Windows uses `MONITOR_DEFAULTTONEAREST` so it **never fails** (`:493`). KDE reads `size.left + size.right` (origin plus width) (`:624-625`). |
| 13 | Cursor position | `cursor_pos() -> Option<(i32,i32)>` `K/backend/mod.rs:258`; `K/kwin/mod.rs:838-850` | `WindowsApi::cursor_pos() -> Result<POINT>` `W/windows_api.rs:847-852` | `MacosApi::cursor_pos() -> CGPoint` `M/macos_api.rs:475-479` | KDE is the odd one: it asks the KWin script and **blocks the caller up to 250 ms** (`:846`), falling back to the last position seen; Windows and macOS read it directly. |
@@ -212,7 +212,7 @@ AppKit objects are created or touched on main only: `NSScreen::screens(MainThrea
| `M/monitor_reconciliator.rs:117` | `exec_sync` | `latest_monitor_information` (`:118`) | No | reconciliator thread |
| `M/monitor_reconciliator.rs:383` | `exec_sync` | `arc.lock()` then `load_monitor_information` (`:384-386`) | **Yes** | reconciliator thread, which first `drop(wm)` "because the main thread needs the lock" (`:379-381`) |
| `M/border_manager/mod.rs:157` (`hide_borders_on`) | `exec_sync` | hide `NSWindow`s | No | `M/window_manager.rs:1385`: **under the WM lock** |
| `M/border_manager/mod.rs:307` (`destroy_border`) | `exec_sync` | invalidate the border's AX observer | No | `destroy_all_borders` (while holding `BORDER_STATE`, `:240`) from the event thread (`M/process_event.rs:128, 139`), command threads (`M/process_command.rs:294, 303, 1776, 1802, 1806`), `retile_all` (`M/window_manager.rs:2286`): **all under the WM lock**; and `theme_manager.rs:227` (lock state not examined) |
| `M/border_manager/mod.rs:307` (`destroy_border`) | `exec_sync` | invalidate the border's AX observer | No | `destroy_all_borders` (while holding `BORDER_STATE`, `:240`) from the event thread (`M/process_event.rs:128, 139`), command threads (`M/process_command.rs:294, 303, 1776, 1802, 1806`), `retile_all` (`M/window_manager.rs:2286`): **all under the WM lock**; and the theme manager thread (`M/theme_manager.rs:227`), whose `handle_notifications()` takes no `wm` argument, so it does not hold the WM lock |
| `M/border_manager/border.rs:153` | `exec_sync` | add AX observer sources to the run loop | No | border thread, holding `BORDER_STATE`/`WINDOWS_BORDERS`, not the WM lock |
| `M/border_manager/border.rs:244` (`Border::destroy`) | `exec_sync` | `NSWindow::close` | No | via `destroy_border` (`:313`), same callers as above |
| `M/macos_api.rs:492` (`activate_finder`) | `exec_sync` | activate Finder | No | event thread (`M/process_event.rs:791`): **under the WM lock** |
@@ -308,3 +308,53 @@ The three platforms disagree about whether a frame write has landed when the cal
- **Windows**: `SetWindowPos` is synchronous unless `ASYNC_WINDOW_POS` (`W/windows_api.rs:518-528`), and the same two ideas exist: `set_position` compares the frame to the layout before writing (`W/window.rs:394-396`), and after a drag the windows are looked at again after 250 ms, "a window that is busy with what an earlier move made it do is seen to be left where that put it" (`W/live_resize.rs:713-724`).
So the facts support: **a frame request may complete before, after or never at the requested size; the achieved frame is learned from events or from a separate, possibly slow, query.** They do not support "never read back": section 7, consequence 2.
## 7. Consequences for the seam
The seven consequences of plan step 7, each against the facts above. Status: CONFIRMED (the facts support it as written), CORRECTED (the plan was wrong or too strong), TARGET (not true of any current code; a rule the seam would have to make true).
**(1) The macOS backend owns an id -> {AX element, pid, observer} registry. CONFIRMED, with additions.** `Window` carries element, application and observer and is cloned into other threads (`M/window.rs:417-427`, `M/animation/animator.rs:90-93`), nothing acts from an id today (section 4.2), and KDE already has the id-to-UUID table behind its backend (`K/kwin/state.rs:153-154, 603-611`). Additions: the registry also needs the application element (focus for tabbed apps, the animator's enhanced-UI guard); the per-id bookkeeping that is global today (`WINDOW_RESTORE_POSITIONS`, `PARKED_WINDOWS`, `ARRIVALS`) belongs behind it or beside it; it has to be fed both by start-up enumeration (a title match, `M/macos_api.rs:326-349`) and by AX events (`_AXUIElementGetWindow` can fail, `M/window.rs:294`); an id it does not know must give an error, as KDE's `command` does (`K/kwin/mod.rs:797-806`). The per-window `AXObserver` can stay a platform subsystem (observation only) if the registry does not need to release it.
**(2) The contract is "`set_rect` returns once requested, never read back to confirm; landing is observed through events". CORRECTED.** Not true as stated: macOS reads back (`M/window.rs:944-972`, `M/arrival.rs`, `M/animation/animator.rs:902`), Windows compares before writing (`W/window.rs:394-396`), KDE's `window_rect` returns the request until the event replaces it (`K/kwin/state.rs:594-600`). What the facts support (section 6.1): *`set_rect` is a request. It returns when the request has been made (queued on KDE, issued on Windows and macOS), says nothing about the frame the window ends up with, and may fail only for an unknown or dead window. The achieved frame is reported by events and by `window_rect`, which a backend may serve from a cache that holds the request until an event corrects it; a backend may offer an explicit, possibly slow, read-back, which the layout calls only where it needs the truth (a refused width, the end of a drag).* The shared `FakeBackend` should be able to refuse a size (it already has `min_sizes`, `K/backend/fake.rs:90`) and to delay or drop an event, which it cannot today (no failure injection, section 3.1).
**(3) Every method is callable from any non-main thread; main-thread work hides inside the macOS implementation. CONFIRMED, qualified.** KDE: every call comes from a thread holding the WM lock or from start-up/shutdown, never from the bridge runtime, whose `block_on` would panic (section 3.1). Windows: stateless, callable from any thread; only window creation and message loops are thread-affine (section 3.2). macOS: the platform calls are already made from the event, command, reaper, settle, reconciler and animator threads (section 3.3). Qualifications: (a) "hides inside the implementation" must not mean `exec_sync`: four of the current `exec_sync` sites (`M/border_manager/mod.rs:157, 307`, `M/border_manager/border.rs:244`, `M/macos_api.rs:492`) are reached under the WM lock and are the ingredients of the possible deadlock; the hidden main-thread work should be `exec_async` with a bounded wait or data the implementation already holds (consequence 4). (b) **Five `Backend` methods exist only because KDE delegates workspaces to the compositor** (`ensure_workspaces`, `switch_workspace`, `set_window_workspace`, `window_workspace`, `current_workspaces`, `K/backend/mod.rs:408-432`; table row 18). Windows and macOS keep workspaces in the core and implement them with hide and restore (row 6). The trait cannot require them of all three: use a capability query, or split them into a sub-trait that only KDE implements and a core path for the rest. (c) `maximize` and `set_opacity` are provided no-ops today and are real on KDE and Windows only; macOS has neither (rows 16, 17), so those need the same capability treatment.
**(4) No `Backend` method blocks on the main thread; on macOS `monitors()` reads a cache refreshed by the display callback; rendering uses `exec_async`. TARGET, not current behaviour.** Current macOS: `latest_monitor_information` is a live `NSScreen` query that panics off main (`M/macos_api.rs:212-213`) and its callers run on main through `exec_sync` (`M/monitor_reconciliator.rs:106, 117, 383`). Blocking main dispatches under the WM lock exist at `M/border_manager/mod.rs:157, 307`, `M/border_manager/border.rs:153, 244`, `M/macos_api.rs:492`, plus the unbounded `rx.recv()` for border windows (`M/border_manager/ns_window.rs:135`); the bounded ones are `on_main` (`M/animation/ghost.rs:125-129`, 750 ms). The CG display callback and `NSWorkspace` handlers run on main (section 3.3), so a cache refreshed there is feasible (a `try_send` today, `M/display_reconfiguration_listener.rs:12-30`), but nothing does it yet. Corrections to the rule's wording: KDE's own contract says "Queries never block on the compositor" (`K/backend/mod.rs:179`) and is also violated, by `cursor_pos` (up to 250 ms, `K/kwin/mod.rs:846`) and by the six `block_on` methods (section 3.1); so the seam rule should be "no `Backend` method waits for the main thread of its own platform, and any method that waits for anything is listed and bounded", which Windows (`SetWindowPos` waiting for the target, unless async, `W/windows_api.rs:518-520`) and KDE also need.
**(5) Borders, stackbars, ghost/DWM, focus-follows-mouse, AX observers, the event tap, SkyLight batching and pan stay in platform crates, feeding the core through the thin event vocabulary. CONFIRMED for most; three corrections.**
- *Focus-follows-mouse* is not platform-only: KDE and Windows both implement it as a setting (`K/kwin/mod.rs:1024-1048`, `W/windows_api.rs:1224-1257`); macOS has none (correction 9). It belongs in the trait as an optional setting.
- *Borders on KDE* are drawn by the compositor and reached through `Backend::apply_look` and `set_border_colours` (`K/backend/mod.rs:473, 504`; callers `K/border_manager/mod.rs:199, 289`), so for KDE they are Backend operations, while on Windows and macOS they are the platform's own windows. The split is therefore "a look request that a backend may ignore" (KDE's `Ok(false)`) versus platform crates that draw.
- **SkyLight batching is not confined to the platform layer.** `BatchedUpdates::begin()` brackets groups of window operations from `M/monitor.rs:246, 289`, `M/window_manager.rs:1383` and `M/workspace.rs:1470-1519` (`SLSDisableUpdate` ... `SLSReenableUpdate`): "everything that changes on screen is held back until this is dropped" (`M/skylight.rs:36-45`). Any shared code that does a layout then needs a way to say "these writes appear together" (a batch or transaction scope with a default no-op). KDE already batches by construction (the `Poll` reply, `K/kwin/mod.rs:285-290`); Windows does not.
**(6) `WindowInfo` has optional metadata fields. CONFIRMED.** KDE's `WindowInfo` has `class`, `exe`, `path`, `fullscreen`, `maximized`, `normal` as plain fields (`K/backend/mod.rs:63-91`). macOS has no class, only a bundle identifier, role and subrole (`M/window.rs:842-905`), and asks the app per field over AX; Windows asks per field too (`W/windows_api.rs:866-1052`). Only `id`, `pid`, `rect` and `alive` are available everywhere cheaply; the rest should be `Option` or fetched on demand. `normal`, `fullscreen`, `maximized` have no macOS source.
**(7) macOS setup takes the main run loop from the platform's `main`. CONFIRMED.** macOS `main` owns the `NSApplication`, the run loop, the event tap and the observers and spins the loop itself (`M/main.rs:226-349`), and the shared `WindowManager` carries the run loop as a field (`WindowManager::new(&run_loop, ..)`, `StaticConfig::preload(.., &run_loop)`, `M/main.rs:260-271`). Windows and KDE `main` have no loop to run: they block on a ctrl-c channel (`W/main.rs:350-357`, `K/main.rs:372-379`). So `main` stays per platform. A shared `run` has to accept a "what to do with the calling thread" hook (park for KDE and Windows, spin the loop for macOS), and the run loop must stop being a field of the shared `WindowManager`.
**Findings the plan did not list**
- **(8) Batch/transaction scope**: see (5).
- **(9) Error types differ**: KDE `eyre::Result` (`K/backend/mod.rs:325`), Windows `eyre::Result` for some calls and `()` for `ShowWindow`-based ones (rows 5, 6, `W/windows_api.rs:668-684`), macOS `AccessibilityError` and `LibraryError` (`M/window.rs:794-915, 1084`). A shared error type must carry "the window is gone", because macOS uses a failed write as its signal for that (`M/reaper.rs:164-173`).
- **(10) `center_cursor_in(&Rect)` is only honest on Windows and macOS**; KDE ignores the rect (row 14). Either the method becomes "centre on this window" or KDE's contract gets a caveat.
- **(11) Hide is observable on macOS and Windows-`Hide`/`Minimize`**, because it changes ordinary window state (a corner position, `SW_HIDE`, minimized), whereas KDE's park desktop and Windows' `Cloak` do not. The core's habit of keeping its own table of what it hid (`HIDDEN_WINDOWS`, `HIDDEN_HWNDS`, `PARKED_WINDOWS`) exists for that reason and the seam must keep the distinction ("hidden by komorebi" versus "minimized by the user") visible to the core.
## 8. Unverified list
Everything I could not confirm by reading, and how to confirm it.
| # | Item | How to confirm |
|---|---|---|
| 1 | `NSWorkspace` notifications are posted on the main thread, and the CG display callback runs on main (the code assumes both: `M/notification_center_listener.rs:183-229`, `M/display_reconfiguration_listener.rs:76`, `M/main.rs:333-334`) | On a Mac: log `pthread_main_np()` (or `std::thread::current().name()`) in both handlers during a display change, a space change and an app launch; run with the main loop paused for a second to see whether delivery waits |
| 2 | Adding AX observer sources to the main run loop from other threads is safe (`M/process_event.rs:614`, `M/process_command.rs:1758`) | Apple's Thread Safety Summary for `CFRunLoopRef`; on a Mac, a stress test creating windows while a drag is in progress, watching for missed or duplicate notifications |
| 3 | `AXUIElement`/`AXObserver` can be used from several threads (the code asserts `Send + Sync`, `M/lib.rs:282-284, 300-302`) | Apple's Accessibility API documentation; a Mac run with a thread sanitizer on the animator lanes |
| 4 | The possible deadlock in 3.3 | On a Mac: a test that holds the WM lock in a thread that calls `destroy_all_borders` while a `Resize` notification is posted for the reconciliator (inject through `monitor_reconciliator::send_notification`); watch for a hang. Not reproducible on Linux |
| 5 | `dispatch_sync` to the main queue from the main thread deadlocks (relevant to `M/main.rs:280`) | Apple's libdispatch documentation; a Mac test |
| 6 | HWND values always fit in 32 bits on 64-bit Windows | Microsoft's "Interprocess Communication Between 32-bit and 64-bit Applications" (handles are 32-bit significant); on a Windows guest, dump `komorebic state` for a long session and check `0 <= hwnd < 2^32` (440 values from the e2e logs passed, section 4.1) |
| 7 | `WINEVENT_OUTOFCONTEXT` callbacks arrive on the thread that called `SetWinEventHook`; cross-thread `SetWindowPos` waits for the target's thread | Microsoft documentation for `SetWinEventHook` and `SetWindowPos`; log `GetCurrentThreadId` in `win_event_hook` on a guest |
| 8 | Secondary monitors can have negative origins on Windows; AX values on scaled resolutions and mixed-DPI arrangements on macOS | Windows guest with two virtual monitors (the `monitors` scenario); a Mac with a scaled display and one with a different scale factor: compare `CGDisplayBounds`, `NSScreen.frame` and the AX frame of a known window |
| 9 | KWin `frameGeometry` includes the server-side decoration and excludes the shadow; whether a macOS AX frame includes a shadow | KWin scripting documentation; compare AX frame with `CGWindowListCopyWindowInfo` bounds for the same window on a Mac |
| 10 | Whether a macOS window created by an app is always reachable by `kAXWindowsAttribute` and `_AXUIElementGetWindow` so that a registry can be fed (title matching at start-up, `M/application.rs:195-208`) | A Mac run over a set of apps (Electron, Java, tabbed terminals) comparing `CGWindowListCopyWindowInfo` ids with the AX window ids |
| 11 | (closed) Whether `theme_manager.rs:227` calls `destroy_all_borders` while holding the WM lock | Read `M/theme_manager.rs:53-75, 227`: `handle_notifications()` takes no window manager, so it does not |
| 12 | Whether the border thread's unbounded `rx.recv()` (`M/border_manager/ns_window.rs:135`) can hang if the main queue never runs the closure (for example while main is blocked) | Read together with item 4; same Mac test |
| 13 | The Windows paths of every `WindowsApi` call: section 3.2 lists thread entry points and examples, not every call chain | `cargo` call graph or a `tracing` run that logs the thread name per `WindowsApi` call in a scenario |
| 14 | The KDE `block_on` panics inside a runtime thread | Tokio documentation; a unit test calling a `block_on` method from `Handle::spawn` |
| 15 | Anything about runtime behaviour: this document is built from reading only; nothing was compiled or run | Run the three gates of the progress log (KDE fast tier, Windows scenarios, macOS by hand) when the trait exists |