From 05d87908c55d50765a8eddc5cce9d3669a0c8f02 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Tue, 27 Oct 2026 06:14:36 -0700 Subject: [PATCH] feat(recorder): orchestrate a recording `komorebi-recorder record` starts every source in the order that makes the non-video sources a superset of the video, stops them in reverse, and checkpoints the manifest as it goes, so that a recorder that is killed leaves a session `reindex` can recover. `--no-video` records everything but the screen, and Ctrl-C or `--duration` stops and finalizes a recording. The format of `annotations.jsonl`, the append-only file that bug regions, notes and findings are written to, is defined here too. The command table arrives with it, with `displays` and `reindex`, and with the text-and-JSON conventions the later commands share. --- Cargo.lock | 102 ++ README.md | 12 + dependencies.json | 27 + docs/usage/recording-a-bug-repro.md | 179 ++ komorebi-recorder/Cargo.toml | 3 + komorebi-recorder/src/analysis/guard.rs | 239 +++ komorebi-recorder/src/analysis/mod.rs | 5 +- komorebi-recorder/src/analysis/timespec.rs | 602 +++++++ komorebi-recorder/src/annotations.rs | 1727 +++++++++++++++++++ komorebi-recorder/src/cli/mod.rs | 139 ++ komorebi-recorder/src/cli/record.rs | 266 +++ komorebi-recorder/src/lib.rs | 12 + komorebi-recorder/src/main.rs | 17 +- komorebi-recorder/src/recorder.rs | 1813 ++++++++++++++++++++ komorebi-recorder/src/recovery.rs | 680 ++++++++ komorebi-recorder/src/testkit.rs | 652 +++++++ 16 files changed, 6462 insertions(+), 13 deletions(-) create mode 100644 docs/usage/recording-a-bug-repro.md create mode 100644 komorebi-recorder/src/analysis/guard.rs create mode 100644 komorebi-recorder/src/analysis/timespec.rs create mode 100644 komorebi-recorder/src/annotations.rs create mode 100644 komorebi-recorder/src/cli/mod.rs create mode 100644 komorebi-recorder/src/cli/record.rs create mode 100644 komorebi-recorder/src/recorder.rs create mode 100644 komorebi-recorder/src/recovery.rs create mode 100644 komorebi-recorder/src/testkit.rs diff --git a/Cargo.lock b/Cargo.lock index 0fb5ee19..1a3f3aa6 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -140,6 +140,12 @@ version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" +[[package]] +name = "cfg_aliases" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724" + [[package]] name = "chrono" version = "0.4.44" @@ -257,6 +263,17 @@ version = "0.8.21" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28" +[[package]] +name = "ctrlc" +version = "3.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e0b1fab2ae45819af2d0731d60f2afe17227ebb1a1538a236da84c93e9a60162" +dependencies = [ + "dispatch2", + "nix", + "windows-sys 0.61.2", +] + [[package]] name = "dirs" version = "6.0.0" @@ -290,6 +307,12 @@ dependencies = [ "objc2", ] +[[package]] +name = "dunce" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813" + [[package]] name = "dyn-clone" version = "1.0.20" @@ -515,8 +538,10 @@ dependencies = [ "clap", "color-eyre", "crossbeam-channel", + "ctrlc", "dirs", "dispatch2", + "dunce", "libc", "objc2", "objc2-av-foundation", @@ -530,6 +555,7 @@ dependencies = [ "schemars", "serde", "serde_json_lenient", + "sysinfo", "uds_windows", "windows", ] @@ -607,6 +633,27 @@ dependencies = [ "simd-adler32", ] +[[package]] +name = "nix" +version = "0.31.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d6d0705320c1e6ba1d912b5e37cf18071b6c2e9b7fa8215a1e8a7651966f5d3" +dependencies = [ + "bitflags", + "cfg-if", + "cfg_aliases", + "libc", +] + +[[package]] +name = "ntapi" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3b335231dfd352ffb0f8017f3b6027a4917f7df785ea2143d8af2adc66980ae" +dependencies = [ + "winapi", +] + [[package]] name = "num-traits" version = "0.2.19" @@ -730,6 +777,16 @@ dependencies = [ "objc2", ] +[[package]] +name = "objc2-io-kit" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33fafba39597d6dc1fb709123dfa8289d39406734be322956a69f0931c73bb15" +dependencies = [ + "libc", + "objc2-core-foundation", +] + [[package]] name = "objc2-io-surface" version = "0.3.2" @@ -1090,6 +1147,20 @@ dependencies = [ "unicode-ident", ] +[[package]] +name = "sysinfo" +version = "0.38.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92ab6a2f8bfe508deb3c6406578252e491d299cbbf3bc0529ecc3313aee4a52f" +dependencies = [ + "libc", + "memchr", + "ntapi", + "objc2-core-foundation", + "objc2-io-kit", + "windows", +] + [[package]] name = "tempfile" version = "3.27.0" @@ -1321,6 +1392,28 @@ dependencies = [ "semver", ] +[[package]] +name = "winapi" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" +dependencies = [ + "winapi-i686-pc-windows-gnu", + "winapi-x86_64-pc-windows-gnu", +] + +[[package]] +name = "winapi-i686-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" + +[[package]] +name = "winapi-x86_64-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" + [[package]] name = "windows" version = "0.62.2" @@ -1449,6 +1542,15 @@ dependencies = [ "windows-targets 0.53.5", ] +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + [[package]] name = "windows-targets" version = "0.52.6" diff --git a/README.md b/README.md index e980eb28..74650f1a 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,18 @@ cargo install --path komorebi-recorder --locked `komorebi-recorder.exe` and, with it, `komorebi-recorder-gui.exe` from a Mac. `nix run github:LGUG2Z/komorebi-recorder` runs the latest commit without a checkout. +## Record a bug + +```sh +komorebi-recorder displays # which displays can be recorded +komorebi-recorder record --duration 30 --out ./repro +``` + +On macOS the terminal needs the Screen Recording permission, as `komorebi` does. For a useful recording, start komorebi +with `--log-level trace` first: the recorder never changes komorebi's log level, it only warns. A session made with +`--no-video` has everything but the screen. [Recording a bug repro](docs/usage/recording-a-bug-repro.md) has the rest: +what is captured on each OS, docking, sleep and lock, and recovering a recording after a crash. + ## How it fits together Two things vary independently: the _host_ the recorder runs on (macOS or Windows) and the _flavor_ of komorebi it diff --git a/dependencies.json b/dependencies.json index b8efaa19..8d22c4fe 100644 --- a/dependencies.json +++ b/dependencies.json @@ -32,9 +32,11 @@ "crc32fast 1.5.0 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-channel 0.5.15 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-utils 0.8.21 registry+https://github.com/rust-lang/crates.io-index", + "ctrlc 3.5.2 registry+https://github.com/rust-lang/crates.io-index", "dirs 6.0.0 registry+https://github.com/rust-lang/crates.io-index", "dirs-sys 0.5.0 registry+https://github.com/rust-lang/crates.io-index", "dispatch2 0.3.1 registry+https://github.com/rust-lang/crates.io-index", + "dunce 1.0.5 registry+https://github.com/rust-lang/crates.io-index", "dyn-clone 1.0.20 registry+https://github.com/rust-lang/crates.io-index", "errno 0.3.14 registry+https://github.com/rust-lang/crates.io-index", "eyre 0.6.12 registry+https://github.com/rust-lang/crates.io-index", @@ -52,12 +54,14 @@ "libc 0.2.186 registry+https://github.com/rust-lang/crates.io-index", "lock_api 0.4.14 registry+https://github.com/rust-lang/crates.io-index", "miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index", + "ntapi 0.4.3 registry+https://github.com/rust-lang/crates.io-index", "num-traits 0.2.19 registry+https://github.com/rust-lang/crates.io-index", "objc2-av-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-core-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-core-graphics 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-core-media 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-core-video 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "objc2-io-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-screen-capture-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "object 0.37.3 registry+https://github.com/rust-lang/crates.io-index", "once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index", @@ -87,6 +91,7 @@ "thread_local 1.1.9 registry+https://github.com/rust-lang/crates.io-index", "unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index", "utf8parse 0.2.2 registry+https://github.com/rust-lang/crates.io-index", + "winapi 0.3.9 registry+https://github.com/rust-lang/crates.io-index", "windows 0.62.2 registry+https://github.com/rust-lang/crates.io-index", "windows-collections 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "windows-core 0.62.2 registry+https://github.com/rust-lang/crates.io-index", @@ -100,6 +105,7 @@ "windows-sys 0.52.0 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.59.0 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.60.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-sys 0.61.2 registry+https://github.com/rust-lang/crates.io-index", "windows-targets 0.52.6 registry+https://github.com/rust-lang/crates.io-index", "windows-targets 0.53.5 registry+https://github.com/rust-lang/crates.io-index", "windows-threading 0.2.1 registry+https://github.com/rust-lang/crates.io-index", @@ -119,6 +125,12 @@ "ryu 1.0.23 registry+https://github.com/rust-lang/crates.io-index" ] ], + [ + "CC0-1.0", + [ + "dunce 1.0.5 registry+https://github.com/rust-lang/crates.io-index" + ] + ], [ "LicenseRef-Komorebi-2.0", [ @@ -140,6 +152,7 @@ "bitflags 2.11.1 registry+https://github.com/rust-lang/crates.io-index", "block2 0.6.2 registry+https://github.com/rust-lang/crates.io-index", "cfg-if 1.0.4 registry+https://github.com/rust-lang/crates.io-index", + "cfg_aliases 0.2.1 registry+https://github.com/rust-lang/crates.io-index", "chrono 0.4.44 registry+https://github.com/rust-lang/crates.io-index", "clap 4.6.1 registry+https://github.com/rust-lang/crates.io-index", "clap_builder 4.6.0 registry+https://github.com/rust-lang/crates.io-index", @@ -152,6 +165,7 @@ "crc32fast 1.5.0 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-channel 0.5.15 registry+https://github.com/rust-lang/crates.io-index", "crossbeam-utils 0.8.21 registry+https://github.com/rust-lang/crates.io-index", + "ctrlc 3.5.2 registry+https://github.com/rust-lang/crates.io-index", "dirs 6.0.0 registry+https://github.com/rust-lang/crates.io-index", "dirs-sys 0.5.0 registry+https://github.com/rust-lang/crates.io-index", "dispatch2 0.3.1 registry+https://github.com/rust-lang/crates.io-index", @@ -174,6 +188,8 @@ "memchr 2.8.0 registry+https://github.com/rust-lang/crates.io-index", "memoffset 0.9.1 registry+https://github.com/rust-lang/crates.io-index", "miniz_oxide 0.8.9 registry+https://github.com/rust-lang/crates.io-index", + "nix 0.31.2 registry+https://github.com/rust-lang/crates.io-index", + "ntapi 0.4.3 registry+https://github.com/rust-lang/crates.io-index", "num-traits 0.2.19 registry+https://github.com/rust-lang/crates.io-index", "objc2 0.6.4 registry+https://github.com/rust-lang/crates.io-index", "objc2-av-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index", @@ -183,6 +199,7 @@ "objc2-core-video 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-encode 4.1.0 registry+https://github.com/rust-lang/crates.io-index", "objc2-foundation 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "objc2-io-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-screen-capture-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "object 0.37.3 registry+https://github.com/rust-lang/crates.io-index", "once_cell 1.21.4 registry+https://github.com/rust-lang/crates.io-index", @@ -212,6 +229,7 @@ "smallvec 1.15.1 registry+https://github.com/rust-lang/crates.io-index", "strsim 0.11.1 registry+https://github.com/rust-lang/crates.io-index", "syn 2.0.117 registry+https://github.com/rust-lang/crates.io-index", + "sysinfo 0.38.4 registry+https://github.com/rust-lang/crates.io-index", "tempfile 3.27.0 registry+https://github.com/rust-lang/crates.io-index", "terminal_size 0.4.4 registry+https://github.com/rust-lang/crates.io-index", "thread_local 1.1.9 registry+https://github.com/rust-lang/crates.io-index", @@ -222,6 +240,7 @@ "uds_windows 1.2.1 registry+https://github.com/rust-lang/crates.io-index", "unicode-ident 1.0.24 registry+https://github.com/rust-lang/crates.io-index", "utf8parse 0.2.2 registry+https://github.com/rust-lang/crates.io-index", + "winapi 0.3.9 registry+https://github.com/rust-lang/crates.io-index", "windows 0.62.2 registry+https://github.com/rust-lang/crates.io-index", "windows-collections 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "windows-core 0.62.2 registry+https://github.com/rust-lang/crates.io-index", @@ -235,6 +254,7 @@ "windows-sys 0.52.0 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.59.0 registry+https://github.com/rust-lang/crates.io-index", "windows-sys 0.60.2 registry+https://github.com/rust-lang/crates.io-index", + "windows-sys 0.61.2 registry+https://github.com/rust-lang/crates.io-index", "windows-targets 0.52.6 registry+https://github.com/rust-lang/crates.io-index", "windows-targets 0.53.5 registry+https://github.com/rust-lang/crates.io-index", "windows-threading 0.2.1 registry+https://github.com/rust-lang/crates.io-index", @@ -243,6 +263,12 @@ "zmij 1.0.21 registry+https://github.com/rust-lang/crates.io-index" ] ], + [ + "MIT-0", + [ + "dunce 1.0.5 registry+https://github.com/rust-lang/crates.io-index" + ] + ], [ "MPL-2.0", [ @@ -271,6 +297,7 @@ "objc2-core-graphics 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-core-media 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-core-video 0.3.2 registry+https://github.com/rust-lang/crates.io-index", + "objc2-io-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index", "objc2-screen-capture-kit 0.3.2 registry+https://github.com/rust-lang/crates.io-index" ] ] diff --git a/docs/usage/recording-a-bug-repro.md b/docs/usage/recording-a-bug-repro.md new file mode 100644 index 00000000..40719196 --- /dev/null +++ b/docs/usage/recording-a-bug-repro.md @@ -0,0 +1,179 @@ +# Recording a Bug Repro + +`komorebi-recorder` records a bug while it happens: the screen, komorebi's log, every komorebi event and the macOS OS +trace, all on one clock, into a single _session directory_. Afterwards you can ask "what was komorebi doing, and what +was the OS doing, at 00:12.5 in the video?" and the other way around. + +``` +komorebi-recorder record --duration 30 # record without a window +``` + +It is built for the situations where komorebi bugs actually show up: laptops that get docked and undocked, woken with the +lid opened, locked and unlocked. Recording carries on through all of that without losing what was already captured; see +[Docking, sleep and lock](#docking-sleep-and-lock). + +## What is captured + +| What | Where it comes from | +| ----------------------- | ----------------------------------------------------------------------------------------------------- | +| Screen | ScreenCaptureKit, one `mp4` per display per contiguous span (a _segment_), with every frame's timestamp | +| komorebi's log | The exact byte range of `komorebi_plaintext.log.` written during the recording | +| komorebi's events | A subscriber socket: every `WindowManagerEvent` / socket message plus the full `State` | +| OS trace: komorebi | `log stream` for komorebi's own process: system frameworks (AX, LaunchServices, ...) as it calls them | +| OS trace: system | Accessibility, SkyLight, HIServices and workspace subsystems | +| OS trace: each app | `log stream` for **every process that owns a window in komorebi's state**, one file per app | +| Recording environment | Displays connecting, disconnecting and sleeping; machine sleep/wake; screen lock; restarts of komorebi or of a log stream | + +The OS trace is what lets you see both seams: komorebi calling into the system, and the system talking to the apps +komorebi is tiling. + +## On Windows + +The same tool records komorebi for Windows, on the same clock, into the same kind of session +directory; a session recorded on one OS can be investigated on the other. What differs: + +| | macOS | Windows | +| --- | --- | --- | +| Screen | ScreenCaptureKit, HEVC | Windows.Graphics.Capture, H.264 (Windows 10 1803+) | +| OS trace | the unified log: komorebi's process, the system, each managed app | WinEvents for every top-level window, folded when repeated, and the System Event Log's warnings and errors and its display, power and GPU providers | +| komorebi's log | its data directory | `%TEMP%\komorebi_plaintext.log.` | +| Permission | Screen Recording, granted to the terminal or app | none | +| Executables | `komorebi-recorder` | `komorebi-recorder.exe` (console: use this to run commands) and `komorebi-recorder-gui.exe` (no console window) | +| Sleep | found from the host clock pausing | heard from Windows as it happens (suspend, resume, lid, displays off, lock) | + +Start komorebi with `komorebi.exe --log-level debug` before recording a bug. (`RUST_LOG=debug` also +prints every dependency's log; `RUST_LOG=komorebi=debug` does not.) +`komorebi-recorder record --no-video` records without the screen. + +## Before you record + +- **Screen Recording permission.** macOS attaches the grant to the terminal (or app) that launches the binary, exactly as + it does for `komorebi` itself. The window shows a "Grant permission" button if it is missing. +- **komorebi's log level.** The recorder never changes komorebi's log level or lifecycle; it only warns. For a useful + repro, start komorebi with `komorebi --log-level trace` (or `RUST_LOG=komorebi=trace`) first. At the default `info` + level most of what the window manager _decided_ is not in the log. + +## Recording + +Press **Record**, reproduce the problem, press **Stop**. The window shows live counters, recent events (a display being +unplugged, a wake) and any warnings. The session is written to +`~/Library/Application Support/komorebi/recordings//` unless you pass `--out`. + +Headless recording is the same thing without the window; Ctrl-C, `SIGTERM` or `--duration` stops and finalizes it: + +``` +komorebi-recorder record --out ./repro --duration 60 +komorebi-recorder displays # list display ids +komorebi-recorder record --display 2 # record just one display +``` + +Useful options: + +| Option | Effect | +| ------------------------------------------ | --------------------------------------------------------------------------------------- | +| `--oslog-apps managed\|all-gui\|none` | Which apps get their own OS trace file (default: those komorebi manages) | +| `--trace-process NAME` / `--trace-pid PID` | Also trace an app komorebi does not manage | +| `--oslog-exclude NAME` | Never trace this (chatty) app | +| `--oslog-level debug\|info\|default` | Unified log level (default `debug`) | +| `--system-process NAME` | Add a system daemon to the `system` stream, e.g. `WindowServer` (see volume note below) | +| `--predicate P` | Replace the `system` stream's predicate | +| `--oslog-all` | One extra unfiltered system-wide stream (very large) | +| `--no-oslog`, `--no-komorebi` | Skip the OS trace, or skip touching komorebi entirely | +| `--no-video` | Do not capture the screen; record everything else on the same clock (see below) | +| `--fps N`, `--retina`, `--codec hevc\|h264` | Video settings (30 fps cap, logical points, HEVC by default) | + +### Without video + +`komorebi-recorder record --no-video` records everything but the screen: komorebi's events and log, the OS trace and +what happened to the recording environment, all on the same clock. Use it on a machine with no +display (or no Screen Recording permission), or when what is on the screen must not be recorded. It asks the system +nothing about displays. A session made this way has no video, so video time `00:00.000` is the moment the recording +started, and there is nothing for `frames` to show. + +## Docking, sleep and lock + +The set of displays, and whether ScreenCaptureKit streams stay alive, changes underneath a laptop all the time. The +recorder is built so that **nothing already captured is put at risk by any of it**. + +- **A display disappears** (unplugged, undocked, lid closed, or it goes to sleep): that display's video file is finalized + on the spot, so it is complete and playable whatever happens next. The other displays carry on untouched. +- **A display appears or returns:** after a one-second settle, it starts a new _segment_ in a new file + (`video--2.mp4`, `-3`, ...). Each segment is a whole file; `session.json` lists every one with its time span. +- **The machine sleeps and wakes:** the wall clock and the host clock are compared many times a second, so a sleep is + noticed the moment the machine wakes and the clock anchors on either side of it are recorded exactly. Every display is + then given a fresh stream rather than trusting the old one, because streams can stall across a sleep without reporting + anything. The host clock pauses while asleep, so video time skips the sleep instead of showing a hole. +- **A stream stalls or dies:** a healthy ScreenCaptureKit stream calls back about thirty times a second even when the + screen is not changing, so silence for a few seconds means a dead stream. That segment ends at its last sign of life and + a new one starts. +- **The screen locks, or another user's session comes to the front:** noted, and the displays are watched as above. +- **A `log stream` process dies** (for instance when logd restarts): it is restarted into the same file, appending. +- **komorebi exits or is restarted:** noted, and when it is running again the recorder re-subscribes and traces the new + process. komorebi not running when recording starts is not an error either. + +All of this is recorded in `recorder.jsonl`. + +### If the recorder dies + +Everything is written as it arrives and the manifest is checkpointed every few seconds, so a crash, a `kill -9` or a +power loss does not lose the session. Video is written as fragmented mp4, which plays up to the last fragment (about a +second) even though it was never finalized, and a static screen is kept moving so that it, too, is flushed. To recover: + +``` +komorebi-recorder reindex +``` + +This closes the segments that were still open (using the video files themselves to decide how much survived), rebuilds +the timeline, and marks the session `recovered`. The queries tell you to do this if you point them at an unfinished +session. + +## The session directory + +``` +session.json manifest: versions, displays and every video segment, clock anchors, log segments, streams, apps, warnings +video-[-].mp4 screen recording of one segment (variable frame rate: frames exist only where the screen changed) +frames-[-].csv every frame's host-clock timestamp +komorebi.log exact slice of komorebi's own log +events.jsonl, states/ subscriber notifications; full State stored only when it changed +state-start.json, state-end.json +recorder.jsonl what happened to the recording environment (displays, sleep/wake, lock, restarts) +oslog/komorebi.ndjson unified log, komorebi's process (oslog/komorebi-.ndjson after a restart) +oslog/system.ndjson unified log, accessibility / SkyLight / workspace subsystems +oslog/apps/-.ndjson unified log, one managed application +timeline.jsonl merged, sorted index pointing into the raw files +README.md generated guide to this session +``` + +Raw files are never rewritten; `timeline.jsonl` only references them, so `komorebi-recorder reindex ` can rebuild +it at any time (including after hand-editing a log). + +## How accurate is the alignment? + +Everything is placed on the host monotonic clock (`mach_absolute_time`). Video frame timestamps and the unified log's +`machTimestamp` are on that clock directly. komorebi's log lines carry UTC wall-clock time and are mapped onto it with +anchors sampled every 5 seconds during the recording and at every sleep, so clock steps and sleep are handled. + +- video to OS trace: within about one frame +- video to komorebi's log: within about one frame plus the wall-clock anchor error (tens of microseconds) +- subscriber events are stamped when the recorder receives them. komorebi sends the notification _after_ it has handled + the event, so the stamp is when the handler **finished**; the `processing event` line in `komorebi.log` is when it + began. + +## Things to know + +- **What can still be missing.** Events from a `log stream` during the moment it was dead and being restarted; komorebi + events while komorebi was not running; the last second or so of video if the recorder is killed rather than stopped; a + display's video while it was asleep or unplugged (there is simply nothing to record). Each of these leaves a line in + `recorder.jsonl` saying so, rather than a silent hole. +- **Windows komorebi manages are found through the window server.** komorebi's `State` has no process ids, so the + recorder resolves window ids to owning processes itself. A process that appears mid-recording gets its own stream as + soon as it shows up in a state or event; events it emitted in the few hundred milliseconds before that are missed + (`session.json` records `first_seen_mach_ns` for each app so you know where each file starts). +- **Volume.** Per-process debug streams are modest, but system-wide daemons are not: `launchservices` alone was ~500 + events/s (~29 MB/min) and `runningboard` ~290 events/s on a normal desktop, which is why they are opt-in. komorebi's + own process emits a few hundred events per second while it is busy. The recorder warns when a stream is abnormal, since + `log stream` can drop events under extreme load. +- **`` values stay redacted.** The tool needs no `sudo` and changes no SIP settings, and it does not do + syscall-level tracing. +- **Privacy.** The video contains whatever was on screen and application logs can contain window titles and URLs. Review + a session before sharing it. diff --git a/komorebi-recorder/Cargo.toml b/komorebi-recorder/Cargo.toml index 8a8d8ada..5a9c4675 100644 --- a/komorebi-recorder/Cargo.toml +++ b/komorebi-recorder/Cargo.toml @@ -10,12 +10,15 @@ chrono = { workspace = true } clap = { workspace = true } color-eyre = { workspace = true } crossbeam-channel = { workspace = true } +ctrlc = { version = "3", features = ["termination"] } dirs = { workspace = true } +dunce = { workspace = true } parking_lot = { workspace = true } png = "0.18" schemars = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } +sysinfo = { workspace = true } [target.'cfg(target_os = "macos")'.dependencies] block2 = "0.6" diff --git a/komorebi-recorder/src/analysis/guard.rs b/komorebi-recorder/src/analysis/guard.rs new file mode 100644 index 00000000..17e64f32 --- /dev/null +++ b/komorebi-recorder/src/analysis/guard.rs @@ -0,0 +1,239 @@ +//! Keeping file access inside the session directory. +//! +//! Session files name other session files (a timeline entry's `file`, an annotation's log +//! reference), and sessions are handed between people and agents. Nothing read from a session may +//! therefore be allowed to point outside it: absolute paths, `..`, and symlinks that lead out are +//! all refused. +//! +//! [`SessionPath`] is the checked session directory, and [`SessionPath::resolve`] is the one way the +//! analysis turns a name from inside a session into a path. [`is_plain_relative`] is the lexical +//! check it starts with. Failures are errors that carry an exit kind, `Usage` for a name that +//! points out and `NotFound` for a directory that is not a session, so a command that hits one +//! fails with the matching exit code (see the `envelope` module). +//! +//! # What is guaranteed, and by what +//! +//! | Rule | Enforced by | Proof | Escape hatch | +//! |---|---|---|---| +//! | A path from [`SessionPath::resolve`] is a plain relative path under the session root | runtime error: `Usage` | `escapes_are_refused` | none | +//! | An existing path whose real location is outside the session is refused, symlinks included | runtime error: `Usage` | `a_symlink_that_leads_out_is_refused` (Unix only) | none | +//! | A path that does not exist yet is checked lexically only | not guaranteed: the symlink check needs the path to exist | none | none | +//! | A [`SessionPath`] is a directory with a manifest | runtime error: `NotFound`, in [`SessionPath::new`] | `a_directory_without_a_manifest_is_not_a_session` | none | +//! | A file whose name is read from the contents of a session is opened through [`SessionPath::resolve`] | convention only: files with a fixed name, such as `events.jsonl`, are opened without it | none | none | + +use super::envelope; +use crate::session::MANIFEST_FILE; +use color_eyre::eyre; +use std::path::Component; +use std::path::Path; +use std::path::PathBuf; + +/// Returns whether `relative` is a non-empty relative path made only of ordinary names: no `..`, +/// no `.`, no root or drive prefix. +/// +/// This looks at the text only. It does not look at the file system, so it cannot see a symlink; +/// [`SessionPath::resolve`] does that. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::guard::is_plain_relative; +/// +/// assert!(is_plain_relative("events.jsonl")); +/// assert!(is_plain_relative("oslog/apps/x.jsonl")); +/// +/// assert!(!is_plain_relative("")); +/// assert!(!is_plain_relative(".")); +/// assert!(!is_plain_relative("../x")); +/// assert!(!is_plain_relative("a/../../x")); +/// assert!(!is_plain_relative("/etc/passwd")); +/// ``` +#[must_use] +pub fn is_plain_relative(relative: &str) -> bool { + !relative.is_empty() + && Path::new(relative) + .components() + .all(|component| matches!(component, Component::Normal(_))) +} + +/// A session directory known to be one, with its real (symlink-free) location. +/// +/// It is constructed only by [`SessionPath::new`], which checks that the directory has a manifest, +/// so a value of this type is guaranteed to name a directory that held one when it was made. Whether +/// the directory still does is not checked again. Files are reached through +/// [`SessionPath::resolve`], which refuses any name that points outside it. +#[derive(Debug, Clone)] +pub struct SessionPath { + root: PathBuf, +} + +impl SessionPath { + /// Returns the checked session directory `dir`, with symlinks resolved. + /// + /// The directory is made canonical with `dunce`, which, unlike [`Path::canonicalize`], does + /// not give a `\\?\` path on Windows, so paths shown to a reader or an agent can be copied. + /// + /// # Errors + /// + /// Both cases are a `NotFound` error: + /// + /// - `dir` cannot be opened (it does not exist or cannot be made canonical): + /// `cannot open : `; + /// - `dir` has no manifest file (`session.json`), so it is not a recording session: + /// ` is not a recording session (no session.json)`. + /// + /// # Example + /// + /// Reading a session needs a session directory on disk, so this example is only compiled. + /// It is covered by `a_directory_without_a_manifest_is_not_a_session` and + /// `plain_relative_paths_resolve_inside_the_session` in this module's tests. + /// + /// ```rust,no_run + /// use komorebi_recorder::analysis::guard::SessionPath; + /// use std::path::Path; + /// + /// let session = SessionPath::new(Path::new("/path/to/session"))?; + /// println!("{}", session.root().display()); + /// # Ok::<(), Box>(()) + /// ``` + pub fn new(dir: &Path) -> eyre::Result { + // not `Path::canonicalize`: on Windows that returns a `\\?\` path, which would then show up + // in every path this tool prints for an agent to copy + let root = dunce::canonicalize(dir).map_err(|error| { + envelope::not_found(format!("cannot open {}: {error}", dir.display())) + })?; + + if !root.join(MANIFEST_FILE).is_file() { + return Err(envelope::not_found(format!( + "{} is not a recording session (no {MANIFEST_FILE})", + dir.display() + ))); + } + + Ok(Self { root }) + } + + /// Returns the session directory: absolute, with symlinks resolved. + #[must_use] + pub fn root(&self) -> &Path { + &self.root + } + + /// Returns the path of `relative` inside the session. It must be a plain relative path (see + /// [`is_plain_relative`]) and, if it exists, must really be inside the session once symlinks + /// are followed. + /// + /// The returned path is `root().join(relative)`: it is not canonicalized, and the file it names + /// is not opened or required to exist. + /// + /// # Errors + /// + /// Both cases are a `Usage` error: + /// + /// - `relative` is not a plain relative path (it is empty, absolute, or has a `..`, a `.` or + /// a drive prefix): `'' is not a path inside the session`; + /// - `relative` exists and, with every symlink followed, is outside the session: + /// `'' leads outside the session`. + /// + /// A path that does not exist passes the second check, because there is nothing to follow. If + /// one of its parent directories is a symlink that leads out, the path is still returned. + /// + /// # Example + /// + /// Covered by `escapes_are_refused` and `a_symlink_that_leads_out_is_refused` in this module's + /// tests; the example needs a session directory on disk, so it is only compiled. + /// + /// ```rust,no_run + /// use komorebi_recorder::analysis::guard::SessionPath; + /// use std::path::Path; + /// + /// let session = SessionPath::new(Path::new("/path/to/session"))?; + /// let events = session.resolve("events.jsonl")?; + /// assert!(events.starts_with(session.root())); + /// assert!(session.resolve("../elsewhere").is_err()); + /// # Ok::<(), Box>(()) + /// ``` + pub fn resolve(&self, relative: &str) -> eyre::Result { + let path = Path::new(relative); + if !is_plain_relative(relative) { + return Err(envelope::usage(format!( + "'{relative}' is not a path inside the session" + ))); + } + + let joined = self.root.join(path); + if let Ok(real) = dunce::canonicalize(&joined) + && !real.starts_with(&self.root) + { + return Err(envelope::usage(format!( + "'{relative}' leads outside the session" + ))); + } + + Ok(joined) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn temp(name: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "komorebi-recorder-guard-{name}-{}", + std::process::id() + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).expect("dir"); + dir + } + + #[test] + fn a_directory_without_a_manifest_is_not_a_session() { + let dir = temp("empty"); + let error = SessionPath::new(&dir).expect_err("not a session"); + assert_eq!(envelope::exit_kind(&error), envelope::ExitKind::NotFound); + let missing = SessionPath::new(&dir.join("nope")).expect_err("missing"); + assert_eq!(envelope::exit_kind(&missing), envelope::ExitKind::NotFound); + } + + #[test] + fn plain_relative_paths_resolve_inside_the_session() { + let dir = temp("plain"); + std::fs::write(dir.join(MANIFEST_FILE), "{}").expect("manifest"); + let session = SessionPath::new(&dir).expect("session"); + + let path = session.resolve("oslog/apps/x.jsonl").expect("resolve"); + assert!(path.starts_with(session.root())); + assert!(path.ends_with("oslog/apps/x.jsonl")); + } + + #[test] + fn escapes_are_refused() { + let dir = temp("escape"); + std::fs::write(dir.join(MANIFEST_FILE), "{}").expect("manifest"); + let session = SessionPath::new(&dir).expect("session"); + + for bad in ["../x", "a/../../x", "/etc/passwd", "", "."] { + assert!(session.resolve(bad).is_err(), "{bad:?} should be refused"); + } + } + + #[cfg(unix)] + #[test] + fn a_symlink_that_leads_out_is_refused() { + let outside = temp("outside"); + std::fs::write(outside.join("secret.txt"), "x").expect("secret"); + let dir = temp("symlink"); + std::fs::write(dir.join(MANIFEST_FILE), "{}").expect("manifest"); + std::os::unix::fs::symlink(&outside, dir.join("link")).expect("symlink"); + let session = SessionPath::new(&dir).expect("session"); + + assert!(session.resolve("link/secret.txt").is_err()); + assert!(session.resolve("link").is_err()); + // a symlink that stays inside is fine + std::fs::create_dir_all(dir.join("real")).expect("real"); + std::os::unix::fs::symlink(dir.join("real"), dir.join("alias")).expect("alias"); + assert!(session.resolve("alias").is_ok()); + } +} diff --git a/komorebi-recorder/src/analysis/mod.rs b/komorebi-recorder/src/analysis/mod.rs index 54b95dd5..2ae9d273 100644 --- a/komorebi-recorder/src/analysis/mod.rs +++ b/komorebi-recorder/src/analysis/mod.rs @@ -3,10 +3,13 @@ //! Everything here reads a session directory and produces plain serializable values, so the same //! answers serve the command line and anything else that wants them. //! This module holds the parts every command shares: the JSON envelope and exit codes -//! ([`envelope`]) and how an event or a log line is named ([`ids`]). +//! ([`envelope`]), how a point in time is named ([`timespec`], [`ids`]) and the guard that keeps +//! file access inside the session ([`guard`]). pub mod classify; pub mod envelope; pub mod events; pub mod flavor; +pub mod guard; pub mod ids; +pub mod timespec; diff --git a/komorebi-recorder/src/analysis/timespec.rs b/komorebi-recorder/src/analysis/timespec.rs new file mode 100644 index 00000000..39f07a62 --- /dev/null +++ b/komorebi-recorder/src/analysis/timespec.rs @@ -0,0 +1,602 @@ +//! Naming a moment: every command that takes a time takes any of these. +//! +//! | form | meaning | +//! |---|---| +//! | `12.5`, `1:02.5`, `-1.5` | video time, see [`crate::timecode`] | +//! | `wall:2026-10-26T20:00:00Z` | a UTC time (RFC 3339) | +//! | `mach:123456789` | the recorder's master clock, in nanoseconds | +//! | `event:12`, `log:345`, `incident:2` | when that record happened | +//! | `bug:a-3f9c1e02`, `bug:a-3f9c1e02.start`, `bug:a-3f9c1e02.end` | an annotation's start or end | +//! +//! Any of them can be followed by `+3s` or `-500ms` to move it. The units are `ms`, `s` and `m` +//! (minutes), and an offset without one (`12.5+3`) is not an offset. An event or annotation can be +//! followed by `.start` or `.end` first (`bug:a-3f9c1e02.end+2s`); the default is the start. The +//! suffix is accepted after any item reference, but only an event and an annotation have two edges: +//! on a log line or an incident it changes nothing. +//! +//! Resolving a name never guesses: an unknown event, a log line without a timestamp or an +//! annotation that does not exist is an error with the "not found" exit code. The one exception is +//! an annotation whose end was never set, which ends when the recording did. +//! +//! # How a name is read +//! +//! A name is read in two steps, and both are in this module. [`TimeSpec`]'s [`FromStr`] splits off +//! the offset and reads the rest as an [`Anchor`], with no session needed: this checks the syntax +//! only. [`TimeSpec::resolve`] then turns the anchor into a moment on the master clock with the +//! session's [`Manifest`] (for video time and wall time) and a [`Lookup`] (for the things a name +//! can point at), and adds the offset. The result is a [`Resolved`], on both the master clock and +//! the video timeline. +//! +//! The master clock is the host's master monotonic clock, in nanoseconds; fields named +//! `*_mach_ns` are readings of it (`mach_` is a historical spelling, and the manifest's +//! `host.clock` says `mach`, `qpc` or `std`). +//! +//! # Example +//! +//! ```rust +//! use komorebi_recorder::analysis::ids::ItemRef; +//! use komorebi_recorder::analysis::timespec::{Anchor, Edge, TimeSpec}; +//! +//! // a video time, moved three seconds later +//! let spec: TimeSpec = "1:02.5+3s".parse()?; +//! assert_eq!(spec.anchor, Anchor::Video(62.5)); +//! assert_eq!(spec.offset_s, 3.0); +//! +//! // when komorebi finished handling event 12, half a second before +//! let spec: TimeSpec = "event:12.end-500ms".parse()?; +//! assert_eq!( +//! spec.anchor, +//! Anchor::Item { item: ItemRef::Event(12), edge: Edge::End } +//! ); +//! assert_eq!(spec.offset_s, -0.5); +//! +//! // a UTC time. The `+01:00` zone is not an offset: it does not end in a unit. +//! let spec: TimeSpec = "wall:2026-10-26T20:00:00+01:00".parse()?; +//! assert_eq!(spec.offset_s, 0.0); +//! +//! // nonsense is an error that describes what was expected +//! let error = "soon".parse::().unwrap_err(); +//! assert_eq!(error.to_string(), "invalid timecode 'soon'"); +//! # Ok::<(), Box>(()) +//! ``` + +use super::envelope; +use super::ids::ItemRef; +use super::ids::is_annotation_id; +use crate::clock::ClockMap; +use crate::session::Manifest; +use crate::timecode; +use chrono::DateTime; +use chrono::Utc; +use color_eyre::eyre; +use std::str::FromStr; + +/// Which end of a span a name means: an event or an annotation has a start and an end. +/// +/// The default is [`Edge::Start`], which is what a name with no `.start` or `.end` means. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum Edge { + /// The start: for an event, when komorebi began handling it, where the log has it; for an + /// annotation, its start. + #[default] + Start, + /// The end: for an event, when the notification was received; for an annotation, its end, or + /// the end of the recording if it has none. + End, +} + +/// The point in the session a [`TimeSpec`] starts from, before its offset is added. +#[derive(Debug, Clone, PartialEq)] +pub enum Anchor { + /// A time on the video timeline, in seconds: `12.5`. It is negative before the video's `t = 0`. + Video(f64), + /// A UTC time (`wall:...`), mapped to the master clock through the session's clock anchors. + Wall(DateTime), + /// A reading of the master clock in nanoseconds (`mach:...`). + Mach(u64), + /// When a recorded item happened: an event, a log line, an incident or an annotation. `edge` + /// picks the start or the end of an event or an annotation. + Item { + /// The thing pointed at. + item: ItemRef, + /// Which end of it. + edge: Edge, + }, +} + +/// A parsed time argument: an [`Anchor`] and an offset to move it by. +/// +/// Parse one from text with [`str::parse`], which needs no session, and turn it into a moment with +/// [`TimeSpec::resolve`]. The module documentation has the forms a time can take. +/// +/// # Errors +/// +/// Parsing fails with a usage error (the exit kind `Usage` of the `envelope` module), whose +/// message describes what was expected, when: +/// +/// - the text is empty or only whitespace: `an empty time`; +/// - a `wall:` time is not RFC 3339: `'': expected an RFC 3339 time like +/// wall:2026-10-26T19:43:35.062613Z`; +/// - a `mach:` time is not a whole number of nanoseconds: `'': mach: takes nanoseconds, e.g. +/// mach:123456`; +/// - the text starts like an item reference (`event:`, `log:`, `incident:`, `ann:`, `bug:`, +/// `note:`, `finding:`) or is an annotation id, and does not parse as one: see [`ItemRef`]; +/// - anything else is not a video timecode: `invalid timecode ''`, where the text is what +/// remains after an offset was split off (see [`timecode::parse`]). +/// +/// Nothing about the session is checked here: `event:99999` parses. +/// +/// # Example +/// +/// ```rust +/// use komorebi_recorder::analysis::timespec::{Anchor, TimeSpec}; +/// +/// let spec: TimeSpec = "mach:5-9s".parse()?; +/// assert_eq!(spec.anchor, Anchor::Mach(5)); +/// assert_eq!(spec.offset_s, -9.0); +/// +/// // an offset needs a unit, so this is not an offset and not a timecode +/// assert!("12.5+3".parse::().is_err()); +/// # Ok::<(), Box>(()) +/// ``` +#[derive(Debug, Clone, PartialEq)] +pub struct TimeSpec { + /// Where the name points, before the offset. + pub anchor: Anchor, + /// Added to the anchor, in seconds; negative to move earlier. 0 when the name has no offset. + pub offset_s: f64, +} + +/// A moment on both clocks: what a [`TimeSpec`] resolves to. +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct Resolved { + /// The moment on the host's master monotonic clock, in nanoseconds (`mach_` is a historical + /// spelling). It is never negative: a moment before the clock's zero is 0. + pub mach_ns: u64, + /// The same moment on the video timeline, in seconds since the video's `t = 0`. Negative before + /// the video started. + pub video_s: f64, +} + +/// The lookups a [`TimeSpec`] needs from a session: when an event, a log line, an incident or an +/// annotation happened. +/// +/// [`TimeSpec::resolve`] calls it for an [`Anchor::Item`]. It is implemented over the real files by +/// the analysis facade (`Analysis`) and by fakes in tests, so a name can be resolved without a +/// session on disk. Every method returns nanoseconds on the master clock, and has no default: an +/// implementor writes all four. +/// +/// An item that does not exist, or has no time, should be a not-found error (the `NotFound` exit +/// kind of the `envelope` module), which [`TimeSpec::resolve`] passes on, so that a name never +/// resolves to a guess. Nothing enforces that for an implementor. +/// +/// # Example +/// +/// A lookup with one event and one annotation, and a manifest whose video starts at 1 second +/// on the master clock: +/// +/// ```rust +/// use color_eyre::eyre; +/// use komorebi_recorder::analysis::timespec::{Edge, Lookup, TimeSpec}; +/// use komorebi_recorder::clock::Anchor; +/// use komorebi_recorder::session::{Manifest, Moment}; +/// +/// struct Known; +/// +/// impl Lookup for Known { +/// fn event_mach_ns(&self, seq: u64, edge: Edge) -> eyre::Result { +/// match (seq, edge) { +/// (1, Edge::Start) => Ok(4_000_000_000), +/// (1, Edge::End) => Ok(4_500_000_000), +/// _ => eyre::bail!("no event #{seq}"), +/// } +/// } +/// fn log_mach_ns(&self, line: u64) -> eyre::Result { +/// eyre::bail!("no log line {line}") +/// } +/// fn incident_mach_ns(&self, number: u64) -> eyre::Result { +/// eyre::bail!("no incident {number}") +/// } +/// fn annotation_span(&self, id: &str) -> eyre::Result<(u64, Option)> { +/// match id { +/// "a-00000001" => Ok((2_000_000_000, None)), // never closed +/// _ => eyre::bail!("no annotation {id}"), +/// } +/// } +/// } +/// +/// let start = Moment { mach_ns: 1_000_000_000, wall_us: 1_000_000 }; +/// let mut manifest = Manifest::new( +/// start, +/// vec![Anchor { mach_ns: 1_000_000_000, wall_us: 1_000_000 }], +/// ); +/// manifest.video_t0_mach_ns = Some(1_000_000_000); +/// manifest.stop = Some(Moment { mach_ns: 10_000_000_000, wall_us: 10_000_000 }); +/// +/// let resolve = |text: &str| text.parse::()?.resolve(&manifest, &Known); +/// +/// // the end of event 1 is 4.5 s on the master clock, which is 3.5 s into the video +/// let resolved = resolve("event:1.end")?; +/// assert_eq!(resolved.mach_ns, 4_500_000_000); +/// assert_eq!(resolved.video_s, 3.5); +/// +/// // an annotation that was never closed ends when the recording did +/// assert_eq!(resolve("bug:a-00000001.end")?.mach_ns, 10_000_000_000); +/// +/// // an item the lookup does not know is an error, not a guess +/// assert!(resolve("event:2").is_err()); +/// # Ok::<(), Box>(()) +/// ``` +pub trait Lookup { + /// Returns when event `seq` happened. [`Edge::Start`] is when komorebi began handling it where + /// known, [`Edge::End`] when the notification was received. + /// + /// # Errors + /// + /// Returns an error if the session has no such event. + fn event_mach_ns(&self, seq: u64, edge: Edge) -> eyre::Result; + + /// Returns when line `line` of komorebi's recorded log was written. Lines are numbered from 1. + /// + /// # Errors + /// + /// Returns an error if the log has no such line, or the line has no time. + fn log_mach_ns(&self, line: u64) -> eyre::Result; + + /// Returns when incident `number` of the recorder's incident log happened. Incidents are + /// numbered from 1. + /// + /// # Errors + /// + /// Returns an error if the session recorded no incidents, or has no such one. + fn incident_mach_ns(&self, number: u64) -> eyre::Result; + + /// Returns an annotation's `(start, end)`; the end is `None` when it has none. + /// + /// # Errors + /// + /// Returns an error if the session has no annotation with this id. + fn annotation_span(&self, id: &str) -> eyre::Result<(u64, Option)>; +} + +impl FromStr for TimeSpec { + type Err = eyre::Report; + + fn from_str(input: &str) -> Result { + let trimmed = input.trim(); + if trimmed.is_empty() { + return Err(envelope::usage("an empty time")); + } + + let (head, offset_s) = split_offset(trimmed); + Ok(Self { + anchor: parse_anchor(head, input)?, + offset_s, + }) + } +} + +/// Split a trailing `+3s` / `-500ms` off. The tail must end in a unit, so a `+02:00` time zone or +/// a `-` inside an id is never taken for an offset. +fn split_offset(text: &str) -> (&str, f64) { + for (index, character) in text.char_indices().rev() { + if index == 0 || (character != '+' && character != '-') { + continue; + } + + let tail = &text[index + 1..]; + if !(tail.ends_with('s') || tail.ends_with('m')) { + continue; + } + + if let Ok(span) = timecode::parse_span(tail) { + let signed = if character == '-' { -span } else { span }; + return (&text[..index], signed); + } + } + + (text, 0.0) +} + +fn parse_anchor(head: &str, original: &str) -> eyre::Result { + if let Some(rest) = head.strip_prefix("wall:") { + let time = DateTime::parse_from_rfc3339(rest).map_err(|_| { + envelope::usage(format!( + "'{original}': expected an RFC 3339 time like wall:2026-10-26T19:43:35.062613Z" + )) + })?; + return Ok(Anchor::Wall(time.with_timezone(&Utc))); + } + + if let Some(rest) = head.strip_prefix("mach:") { + let ns = rest.parse().map_err(|_| { + envelope::usage(format!( + "'{original}': mach: takes nanoseconds, e.g. mach:123456" + )) + })?; + return Ok(Anchor::Mach(ns)); + } + + let (body, edge) = match head + .strip_suffix(".start") + .map(|body| (body, Edge::Start)) + .or_else(|| head.strip_suffix(".end").map(|body| (body, Edge::End))) + { + Some((body, edge)) => (body, edge), + None => (head, Edge::Start), + }; + + if ItemRef::has_prefix(body) || is_annotation_id(body) { + return Ok(Anchor::Item { + item: body.parse()?, + edge, + }); + } + + timecode::parse(head) + .map(Anchor::Video) + .map_err(|error| envelope::usage(format!("{error}"))) +} + +impl TimeSpec { + /// Returns the moment this name points at in `manifest`'s session, on the master clock and on + /// the video timeline. + /// + /// The anchor is turned into a reading of the master clock (video time through the manifest's + /// video `t = 0`, wall time through its clock anchors, an item through `lookup`), the offset is + /// added, and a result below 0 becomes 0. + /// + /// # Errors + /// + /// - The `Unusable` exit kind, `the session has no clock anchors`, if the anchor is a `wall:` + /// time and the manifest has no clock anchors to map it with. + /// - Whatever `lookup` returns for an [`Anchor::Item`]: an event, log line, incident or + /// annotation that does not exist is a not-found error (see [`Lookup`]). + /// + /// # Example + /// + /// A moment before the clock started clamps to 0 instead of failing. See [`Lookup`] for an + /// example with items. + /// + /// ```rust + /// use color_eyre::eyre; + /// use komorebi_recorder::analysis::timespec::{Edge, Lookup, TimeSpec}; + /// use komorebi_recorder::session::{Manifest, Moment}; + /// + /// struct Nothing; + /// + /// impl Lookup for Nothing { + /// fn event_mach_ns(&self, seq: u64, _: Edge) -> eyre::Result { + /// eyre::bail!("no event #{seq}") + /// } + /// fn log_mach_ns(&self, line: u64) -> eyre::Result { + /// eyre::bail!("no log line {line}") + /// } + /// fn incident_mach_ns(&self, number: u64) -> eyre::Result { + /// eyre::bail!("no incident {number}") + /// } + /// fn annotation_span(&self, id: &str) -> eyre::Result<(u64, Option)> { + /// eyre::bail!("no annotation {id}") + /// } + /// } + /// + /// let manifest = Manifest::new(Moment { mach_ns: 0, wall_us: 0 }, Vec::new()); + /// + /// let resolved = "mach:5-9s".parse::()?.resolve(&manifest, &Nothing)?; + /// assert_eq!(resolved.mach_ns, 0); + /// + /// // a wall time needs clock anchors to be mapped with, and this manifest has none + /// let error = "wall:2026-10-26T20:00:00Z" + /// .parse::()? + /// .resolve(&manifest, &Nothing) + /// .unwrap_err(); + /// assert_eq!(error.to_string(), "the session has no clock anchors"); + /// # Ok::<(), Box>(()) + /// ``` + pub fn resolve(&self, manifest: &Manifest, lookup: &dyn Lookup) -> eyre::Result { + let base_ns = match &self.anchor { + Anchor::Video(seconds) => manifest.mach_at_video_seconds(*seconds), + Anchor::Mach(ns) => *ns, + Anchor::Wall(time) => ClockMap::new(manifest.anchors.clone()) + .wall_to_mach(time.timestamp_micros()) + .ok_or_else(|| envelope::unusable("the session has no clock anchors"))?, + Anchor::Item { item, edge } => match item { + ItemRef::Event(seq) => lookup.event_mach_ns(*seq, *edge)?, + ItemRef::Log(line) => lookup.log_mach_ns(*line)?, + ItemRef::Incident(number) => lookup.incident_mach_ns(*number)?, + ItemRef::Annotation(id) => { + let (start, end) = lookup.annotation_span(id)?; + match edge { + Edge::Start => start, + // an annotation that was never closed lasts until the recording ended + Edge::End => end.unwrap_or_else(|| session_end_ns(manifest)), + } + } + }, + }; + + let shifted = i128::from(base_ns) + (self.offset_s * 1e9).round() as i128; + let mach_ns = u64::try_from(shifted.max(0)).unwrap_or(u64::MAX); + Ok(Resolved { + mach_ns, + video_s: manifest.video_seconds(mach_ns), + }) + } +} + +/// Returns when the recording ended on the master clock, in nanoseconds. +/// +/// That is the manifest's `stop`, else when video capture ended, else when the recording started. +/// A recording that has not stopped and has no video therefore ends where it began. +#[must_use] +pub fn session_end_ns(manifest: &Manifest) -> u64 { + manifest + .stop + .map(|stop| stop.mach_ns) + .or(manifest.video_end_mach_ns) + .unwrap_or(manifest.start.mach_ns) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::clock::Anchor as ClockAnchor; + use crate::session::Moment; + + struct Fake; + + impl Lookup for Fake { + fn event_mach_ns(&self, seq: u64, edge: Edge) -> eyre::Result { + match (seq, edge) { + (1, Edge::Start) => Ok(4_000_000_000), + (1, Edge::End) => Ok(4_500_000_000), + _ => Err(envelope::not_found(format!("no event {seq}"))), + } + } + + fn log_mach_ns(&self, line: u64) -> eyre::Result { + Ok(1_000_000_000 * line) + } + + fn incident_mach_ns(&self, number: u64) -> eyre::Result { + Err(envelope::not_found(format!("no incident {number}"))) + } + + fn annotation_span(&self, id: &str) -> eyre::Result<(u64, Option)> { + match id { + "a-00000001" => Ok((2_000_000_000, Some(3_000_000_000))), + "a-00000002" => Ok((2_000_000_000, None)), + _ => Err(envelope::not_found(format!("no annotation {id}"))), + } + } + } + + /// Video t=0 is mach 1s; wall `1_000_000us` is mach 1s; the session ended at mach 10s. + fn manifest() -> Manifest { + let mut manifest = Manifest::new( + Moment { + mach_ns: 1_000_000_000, + wall_us: 1_000_000, + }, + vec![ClockAnchor { + mach_ns: 1_000_000_000, + wall_us: 1_000_000, + }], + ); + manifest.video_t0_mach_ns = Some(1_000_000_000); + manifest.stop = Some(Moment { + mach_ns: 10_000_000_000, + wall_us: 10_000_000, + }); + manifest + } + + fn resolve(text: &str) -> eyre::Result { + text.parse::()?.resolve(&manifest(), &Fake) + } + + fn close(a: f64, b: f64) -> bool { + (a - b).abs() < 1e-6 + } + + #[test] + fn video_times_resolve_against_the_manifest() { + let resolved = resolve("2.5").expect("resolve"); + assert_eq!(resolved.mach_ns, 3_500_000_000); + assert!(close(resolved.video_s, 2.5)); + assert!(close(resolve("0:02.5").expect("clock").video_s, 2.5)); + } + + #[test] + fn offsets_move_any_anchor() { + assert!(close(resolve("2.5+1s").expect("plus").video_s, 3.5)); + assert!(close(resolve("2.5-500ms").expect("minus").video_s, 2.0)); + assert!(close( + resolve("event:1.end-1s").expect("event").video_s, + 2.5 + )); + // video t=0 is mach 1s here, so half a second before it is still on the clock + assert!(close( + resolve("-0.5").expect("negative video").video_s, + -0.5 + )); + } + + #[test] + fn mach_and_wall_times_resolve() { + assert!(close( + resolve("mach:3000000000").expect("mach").video_s, + 2.0 + )); + // wall 5s after the epoch is 4s after the anchor at wall 1s: mach 5s, video 4s + let wall = resolve("wall:1970-01-01T00:00:05Z").expect("wall"); + assert!(close(wall.video_s, 4.0)); + // a numeric zone is not an offset + let zoned = resolve("wall:1970-01-01T01:00:05+01:00").expect("zoned"); + assert!(close(zoned.video_s, 4.0)); + let moved = resolve("wall:1970-01-01T00:00:05Z+2s").expect("moved"); + assert!(close(moved.video_s, 6.0)); + } + + #[test] + fn items_resolve_through_the_lookup() { + assert!(close(resolve("event:1").expect("start").video_s, 3.0)); + assert!(close(resolve("event:1.end").expect("end").video_s, 3.5)); + assert!(close(resolve("log:7").expect("log").video_s, 6.0)); + assert!(close(resolve("bug:a-00000001").expect("bug").video_s, 1.0)); + assert!(close( + resolve("bug:a-00000001.end").expect("bug end").video_s, + 2.0 + )); + assert!(close( + resolve("a-00000001.end+1s").expect("bare id").video_s, + 3.0 + )); + } + + #[test] + fn an_unclosed_annotation_ends_with_the_session() { + let end = resolve("bug:a-00000002.end").expect("open-ended"); + assert_eq!(end.mach_ns, 10_000_000_000); + } + + #[test] + fn missing_things_are_not_found_not_guesses() { + for text in ["event:99", "incident:1", "bug:a-0000ffff"] { + let error = resolve(text).expect_err(text); + assert_eq!( + envelope::exit_kind(&error), + envelope::ExitKind::NotFound, + "{text}" + ); + } + } + + #[test] + fn nonsense_is_a_usage_error() { + for text in [ + "", + "soon", + "wall:yesterday", + "mach:x", + "event:one", + "1:2:3:4", + ] { + let error = text + .parse::() + .map(|_| ()) + .expect_err(&format!("{text:?} should not parse")); + assert_eq!( + envelope::exit_kind(&error), + envelope::ExitKind::Usage, + "{text:?}" + ); + } + } + + #[test] + fn times_before_the_clock_started_clamp_to_zero() { + let resolved = resolve("mach:5-9s").expect("clamped"); + assert_eq!(resolved.mach_ns, 0); + } +} diff --git a/komorebi-recorder/src/annotations.rs b/komorebi-recorder/src/annotations.rs new file mode 100644 index 00000000..dff4ae15 --- /dev/null +++ b/komorebi-recorder/src/annotations.rs @@ -0,0 +1,1727 @@ +//! What people and agents say about a recording: where a bug starts and ends, notes, findings. +//! +//! The most important annotation is the **bug region**: the stretch of the recording during which +//! the user saw something wrong, with a description of what it looked like. It is the ground truth +//! of *what* went wrong that every investigation starts from; the rest of the session is evidence +//! of *why*. An agent's conclusion is written back as a `finding` that points at its evidence. +//! +//! They live in `annotations.jsonl`, one JSON object per line, **append-only**: the viewer and an +//! agent may both add to it, even while the recording is still running, and a crash +//! mid-write can only damage the last line. Changing or removing an annotation appends an `edit` or +//! `delete` line for its id; reading folds the lines in order. Times are on the master clock +//! (`*_mach_ns`), not in video seconds, so they stay right if `reindex` moves video t=0. +//! +//! A region whose end was never set is *open-ended*: the bug was still happening when the recording +//! stopped. Readers treat it as ending when the recording did and say so. +//! +//! # The three kinds +//! +//! | [`Kind`] | What it is | Written by | +//! |---|---|---| +//! | [`Kind::Bug`] | a region of the recording where the bug was visible, in the user's words | the viewer, `komorebi-recorder annotate` (author [`AUTHOR_USER`]) | +//! | [`Kind::Note`] | a remark about a moment or region | `komorebi-recorder annotate` | +//! | [`Kind::Finding`] | an agent's conclusion about the cause of a bug, with [`Ref`]s to its evidence | `komorebi-recorder annotate` (author `agent` unless told otherwise) | +//! +//! The kind is a lowercase word in the file, and prints the same way: +//! +//! ```rust +//! use komorebi_recorder::annotations::Kind; +//! +//! assert_eq!(Kind::Finding.to_string(), "finding"); +//! assert_eq!(serde_json::to_string(&Kind::Bug)?, r#""bug""#); +//! assert_eq!(serde_json::from_str::(r#""note""#)?, Kind::Note); +//! # Ok::<(), Box>(()) +//! ``` +//! +//! # Writing and reading +//! +//! | To | Use | Lines appended | +//! |---|---|---| +//! | add an annotation | [`add`] with a [`New`] | one `add` | +//! | change one | [`edit`] with a [`Patch`] | one `edit` carrying only the changed fields | +//! | remove one | [`delete`] | one `delete`, a tombstone: the earlier lines stay | +//! | read them | [`load`], or [`fold`] over text already read | none | +//! | check evidence | [`validate_refs`] | none | +//! +//! Every write goes through [`append`], which serializes writers on `annotations.lock` and +//! closes off a line a crashed writer left unterminated. [`fold`] never fails: a line it cannot +//! understand is skipped and reported in [`Loaded::warnings`], and the rest of the file is still +//! read. +//! +//! # What is enforced here, and what is not +//! +//! This module checks that an end is not before its start ([`add`], [`edit`]) and, on request, that +//! evidence exists ([`validate_refs`]). It does not require a bug to have a description, a finding +//! to have evidence, or a finding to name the bug it is about. +//! [`Annotation::needs_description`] flags a bug that is still without a description. `komorebi-recorder annotate add` is stricter (it requires a +//! description, and evidence for a finding), and a hand-written line is held to neither: [`fold`] +//! accepts it. +//! +//! # Example +//! +//! A user marks a region that is still open, adds the description afterwards, and an agent records +//! its conclusion. All of it is lines in one file, folded on read: +//! +//! ```rust +//! use komorebi_recorder::annotations::{Kind, Ref, fold}; +//! +//! let text = [ +//! r#"{"v":1,"id":"a-00000001","op":"add","kind":"bug","start_mach_ns":2000000000}"#, +//! r#"{"v":1,"id":"a-00000001","op":"edit","end_mach_ns":5000000000,"text":"tiles overlap"}"#, +//! r#"{"v":1,"id":"a-00000002","op":"add","kind":"finding","start_mach_ns":2000000000,"about":"a-00000001","refs":[{"kind":"event","seq":12}]}"#, +//! ] +//! .join("\n"); +//! +//! let loaded = fold(&text); +//! assert!(loaded.warnings.is_empty()); +//! +//! let bug = loaded.get("a-00000001").expect("the bug"); +//! assert_eq!(bug.kind, Kind::Bug); +//! assert_eq!(bug.end_mach_ns, Some(5_000_000_000)); +//! assert_eq!(bug.text, "tiles overlap"); +//! +//! let finding = loaded.get("a-00000002").expect("the finding"); +//! assert_eq!(finding.about.as_deref(), Some("a-00000001")); +//! assert_eq!(finding.refs, [Ref::Event { seq: 12 }]); +//! ``` +//! +//! Writing goes through the file system; [`add`], [`edit`], [`delete`] and [`load`] have examples +//! that use a temporary session directory. + +use crate::analysis::envelope; +use crate::analysis::flavor::Flavor; +use crate::analysis::guard::SessionPath; +use crate::analysis::guard::is_plain_relative; +use crate::analysis::ids; +use crate::clock; +use crate::clock::ClockMap; +use crate::session::Manifest; +use crate::session::Session; +use crate::timeline; +use color_eyre::eyre; +use color_eyre::eyre::WrapErr; +use schemars::JsonSchema; +use serde::Deserialize; +use serde::Serialize; +use std::collections::BTreeMap; +use std::fmt; +use std::fs::OpenOptions; +use std::io::Read; +use std::io::Seek; +use std::io::SeekFrom; +use std::io::Write; +use std::path::Path; +use std::path::PathBuf; +use std::str::FromStr; + +/// The name, inside a session directory, of the file the annotations are appended to. +pub const ANNOTATIONS_FILE: &str = "annotations.jsonl"; +/// The name, inside a session directory, of the file writers lock so that their lines do not +/// interleave. +/// +/// It is created empty and nothing is ever written to it. It is a separate file because Windows +/// locks are mandatory: locking [`ANNOTATIONS_FILE`] itself would make it unreadable for everyone +/// else while a line is added. +pub const ANNOTATIONS_LOCK_FILE: &str = "annotations.lock"; + +/// The version written to every line. +/// +/// [`fold`] skips a line whose version is greater than this one, and reports it in +/// [`Loaded::warnings`]. A line with a lower version is read as written. +pub const LINE_VERSION: u32 = 1; + +/// The author recorded when none is given: [`add`] uses it for a [`New`] without an author, and +/// [`fold`] for an `add` line without one. +pub const AUTHOR_USER: &str = "user"; + +/// The kind of an annotation: `bug`, `note` or `finding`. +/// +/// The kind is fixed when the annotation is added: an edit cannot change it. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +#[serde(rename_all = "lowercase")] +pub enum Kind { + /// A region where the bug was visible, described by the user. + Bug, + /// A remark about a moment or a region. + Note, + /// An agent's conclusion about what caused a bug, pointing at its evidence. + Finding, +} + +impl fmt::Display for Kind { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(match self { + Self::Bug => "bug", + Self::Note => "note", + Self::Finding => "finding", + }) + } +} + +/// The operation a [`Line`] performs on the annotation it names. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum Op { + /// Creates the annotation. A line with no `op` is an `add`. + Add, + /// Changes the fields the line carries and leaves the rest as they were. + Edit, + /// Removes the annotation. The id cannot be added again. + Delete, +} + +/// Evidence a finding points at. +/// +/// Each kind names something in the session, or in komorebi's source, that a reader can open; the +/// annotate command checks that it exists. On the command line a reference is written `event:12`, +/// `log:345`, `log:oslog/komorebi.ndjson:77`, `code:komorebi/src/window.rs:210` or `frame:12.5`. +/// In `annotations.jsonl` and in `--json` output it is an object tagged with `kind`, such as +/// `{"kind":"event","seq":12}`. +/// +/// The text form is read by [`str::parse`] and printed by [`Display`](fmt::Display); the example is +/// on the [`FromStr`] implementation, and [`validate_refs`] does the checking. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)] +#[serde(tag = "kind", rename_all = "lowercase")] +pub enum Ref { + /// A komorebi subscriber event. + Event { + /// The event's sequence number, as in `events.jsonl` and the `#` of the `events` + /// command. + seq: u64, + }, + /// A line of a recorded text file (the komorebi log slice by default). + Log { + /// The file, as a path relative to the session directory. + file: String, + /// The line, counted from 1. + line: u64, + }, + /// A line of komorebi's source, relative to the repository root. + Code { + /// The file, as a path relative to the root of komorebi's repository. + path: String, + /// The line, counted from 1. + line: u64, + }, + /// A moment in the video. + Frame { + /// Seconds of video time: from the first frame of any display. + video_s: f64, + }, +} + +/// The file `log:` refers to when it names no file: komorebi's plaintext log in the session +/// directory. +pub const DEFAULT_LOG_FILE: &str = "komorebi.log"; + +impl fmt::Display for Ref { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::Event { seq } => write!(f, "event:{seq}"), + Self::Log { file, line } => write!(f, "log:{file}:{line}"), + Self::Code { path, line } => write!(f, "code:{path}:{line}"), + Self::Frame { video_s } => write!(f, "frame:{}", crate::timecode::format(*video_s)), + } + } +} + +impl FromStr for Ref { + type Err = eyre::Report; + + /// Reads a reference: `event:12`, `log:345`, `log:oslog/komorebi.ndjson:77`, + /// `code:komorebi/src/window.rs:210` or `frame:12.5`. + /// + /// For `log:` and `code:` the line is what follows the last colon. A `log:` whose rest is a + /// whole number is a line of [`DEFAULT_LOG_FILE`]. The time of a `frame:` is any form + /// [`crate::timecode::parse`] reads. [`Display`](fmt::Display) prints the same forms, with the + /// file of a `log:` always spelled out. + /// + /// # Errors + /// + /// Returns a usage error (`komorebi-recorder` exits with code 2 on it) when the text has no + /// colon, the kind is not `event`, `log`, `code` or `frame`, the sequence number is not a whole + /// number, or a `log:` or `code:` does not end in a colon and a whole number. A `frame:` whose + /// time cannot be parsed returns the error of [`crate::timecode::parse`], which is an ordinary + /// error (exit code 1). + /// + /// This only checks the spelling; whether the thing exists is [`validate_refs`]'s question. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::annotations::Ref; + /// + /// let evidence: Ref = "code:komorebi/src/window.rs:210".parse()?; + /// assert_eq!( + /// evidence, + /// Ref::Code { path: "komorebi/src/window.rs".to_string(), line: 210 }, + /// ); + /// assert_eq!( + /// serde_json::to_string(&evidence)?, + /// r#"{"kind":"code","path":"komorebi/src/window.rs","line":210}"#, + /// ); + /// + /// // `log:` means the komorebi log; printing spells the file out + /// let line: Ref = "log:345".parse()?; + /// assert_eq!(line.to_string(), "log:komorebi.log:345"); + /// assert_eq!(line.to_string().parse::()?, line); + /// + /// // a video time is printed as a timecode + /// let frame: Ref = "frame:12.5".parse()?; + /// assert_eq!(frame.to_string(), "frame:00:12.500"); + /// + /// // a malformed reference is refused, and says what was expected + /// let error = "cat:1".parse::().unwrap_err(); + /// assert_eq!(error.to_string(), "'cat:1': unknown kind of reference"); + /// # Ok::<(), Box>(()) + /// ``` + fn from_str(input: &str) -> Result { + let bad = |why: &str| envelope::usage(format!("'{input}': {why}")); + let (kind, rest) = input.split_once(':').ok_or_else(|| { + bad("expected event:, log:, code:: or frame: