puter/SAMPLING.md

Sampling and events

One cancellable scheduler follows SamplingDemand. No timer is scheduled while paused, or when the app has no visible window, menu-bar, alert, or recording consumer. Settings and startup pages do not request process inventory. Services are sampled only while their page is active. Background CPU/memory/network menu-bar readings use lightweight system counters, not process enumeration or per-app nettop.

CPU time, I/O rates, fan speeds and service state still require samples: public macOS notifications are not a replacement for continuously changing counters. Recording deliberately retains system/process sampling in the background. App-history collection is opportunistic rather than an always-running daemon.

Existing workspace notifications invalidate app and volume inventory; app-event bursts are coalesced over 200ms. Volume enumeration no longer runs every ten seconds. IOKit power-source, memory-pressure and thermal notifications remain. USB/port inventory still reconciles while hardware is being consumed, because the current implementation does not have an IOKit device-matching observer.

Validation: eight SamplingDemand tests cover idle, pause, services, menu-bar, recording and alerts. The native sampler budget test passed: full process sample averaged 65.5ms versus 7.5ms for system-only telemetry on this machine. These are scan-cost measurements, not before/after whole-app CPU or energy measurements.

Profiling-driven corrections

Demand now reads current application hidden state and the visibility, minimized state and occlusion of titled windows. A visible unfocused window remains live. Hide/unhide and window occlusion/minimize notifications reschedule the existing task; each scheduled wake also reconciles live demand before doing any work. There is no added visibility polling timer. Startup and explicit Refresh can request one inventory even without a visible consumer.

Process groups are prepared once per inventory result, outside view evaluation. A bounded executable-path cache includes misses. Table rendering shares one sorted/filtered projection among category rows and the empty-state check; search still preserves matching-member behavior and group identity.

Disk capacity is cached independently of disk activity: initial/manual refresh, volume enumeration, and at most once per minute on visible Performance. Normal telemetry samples reuse the cached capacity instead of querying the filesystem. See PROFILING.md for Release measurements and caveats.