blocker/docs/PERF.md

Performance

Two tables. Targets are from CLAUDE.md section 5 and are fixed. Results is what was actually measured, and it is currently almost empty because almost nothing is built yet.

The separation is deliberate. A single table mixing aspiration with measurement invites reading the aspiration as the result.

Targets (CLAUDE.md section 5)

Metric	Android	Windows / Linux daemon
Idle CPU	~0% (no wakeups without events)	~0%, ≤ 1 wakeup/min when idle
Idle RAM	≤ 30 MB PSS	≤ 15 MB RSS (daemon), UI process exits when its window closes
Block latency (foreground change → block shown)	≤ 150 ms	≤ 150 ms
Daemon binary	—	≤ 5 MB stripped
APK size	≤ 10 MB (release, R8)	—
Battery	no wakelocks outside active enforcement	—

The release profile in the workspace Cargo.toml carries opt-level = "z", LTO, codegen-units = 1, panic = "abort", and strip = true, which is what makes the size budget reachable. scripts/size-check.sh enforces it in CI from the first commit.

Results

Measured on: Ubuntu 26.04 LTS, KDE Plasma 6.6.6, 6 CPUs. Toolchain: rustc 1.98.1.

Metric	Target	Measured	When
Daemon binary (stripped, release)	≤ 5 MB	1.364 MB	2026-10-01, M1
Block latency	≤ 150 ms	not measured	—
Idle CPU	~0%	not measured	—
Idle RAM (daemon)	≤ 15 MB RSS	not measured	—
Idle wakeups	≤ 1/min	not measured	—
APK size	≤ 10 MB	not measured	—

What the 1.364 MB contains, and why it matters. That figure is with bundled SQLite linked in and the daemon actually opening a database — not the 0.279 MB placeholder from M0, which was two println! lines and excluded SQLite entirely through dead-code elimination.

So the honest read is: bundled SQLite costs roughly 1.1 MB of a 5 MB budget. That leaves 3.8 MB for D-Bus, X11, and the UI toolkit. It is a real constraint rather than a comfortable margin, and it is the first number that makes the section 5 budget feel like a budget instead of a formality.

It also makes ADR-4 (rusqlite bundled vs system-linked) a genuine trade-off rather than a settled one: system-linking would recover most of that 1.1 MB at the cost of a runtime dependency on the host's libsqlite3. Recorded as an open question.

How to measure

Linux daemon

# Binary size — the gate CI runs
scripts/size-check.sh

# Idle RSS
./systemctl --user start blocker
ps -o rss= -C blocker-daemon | awk '{printf "%.1f MB\n", $1/1024}'

# Idle CPU — sample over a minute, not instantaneously
pidstat -p "$(pidof blocker-daemon)" 10 6

# Block latency — timestamp on the compositor event, timestamp on the window map
# TODO: script this in M2-Linux once the KWin backend emits both.

perf stat -e context-switches,cpu-migrations is useful for the wakeup count. If idle wakeups exceed one per minute, a timer is firing that next_wakeup did not ask for — that is the first thing to look for.

Windows

Process Explorer, or ETW. The relevant counters are working set (RAM) and the process's CPU over a sampled window.

Android

adb shell dumpsys meminfo vu.valiq.blocker     # PSS, must be <= 30 MB
adb shell dumpsys batterystats vu.valiq.blocker
adb shell am profile start --sampling 1 vu.valiq.blocker /data/local/tmp/p

Perfetto for the wakeup analysis. A wakeup from the blocked package when nothing is happening is a bug in next_wakeup accounting, and battery stats will show it long before a user complains.

Why idle is hard, and what breaks it

The budget is zero idle wakeups, so the common causes are worth naming.

1. A timer that fires to check something. The engine's job is to make these unnecessary. Every condition that contributes a next_wakeup boundary is a deliberate, named commitment. A new timer that does not correspond to a boundary is a bug.
2. Conditions that should contribute no boundary but do. Wi-Fi and location schedules are changed by OS events — NetworkManager's callback, the geofencing API. Arming a timer for them would be a wakeup for nothing. wifi_schedule_declares_no_time_wakeup pins this.
3. The UI holding a GL context. A resident graphics context costs both RAM and compositor wakeups. This is why the daemon and the block window are separate processes: the window exits when the block lifts, and nothing holds a context while idle.
4. Unbounded Vec growth in the engine. blocked_apps is rebuilt per evaluation. With a handful of schedules it is small, but a schedule set in the thousands would allocate per focus event. next_wakeup returning None means the daemon is asleep and this does not matter, which is exactly why the budget and the design reinforce each other.
5. Storage polling. Nothing in the design polls the database. If a future change introduces it, it will show up here first.

Recording a result

Add a row to the table above with the date and the tool used. Then note in the commit message whether the change touches the hot path — section 9 requires a re-measurement when it does.

A milestone is not done until its acceptance checks pass and its numbers are recorded here (section 7).