Skip to main content

brightness contract

The GTK shell exports org.gnome.Shell.Brightness at /org/gnome/Shell/Brightness: readonly boolean HasBrightnessControl, void SetDimming(b) and SetAutoBrightnessTarget(d), and the payloadless BrightnessChanged user-update signal. This candidate still requires fresh Rust, GTK and native VM qualification; source and controlled fixtures do not qualify physical backlight hardware.

Positive capability requires a bounded readable kernel backlight associated by its actual raw type and canonical DRM connector ancestry with the exact compositor-owned GPU and connector object, plus the actual system bus. A new append-only native inventory carries the selected char-device rdev, kernel connector ID and canonical object identity; OutputInfo stays binary unchanged. The authority is captured at actual discovery, gated by the live owned FD and session activity at publication, and revalidated at brightness admission and completion. Empty authority explicitly revokes prior association. Same-name connectors on other GPUs never confer authority. Nested sessions have no native authority; the controlled GTK fixture supplies a bounded, FD-verified synthetic manifest only beside its explicit backlight-root override. The native receipt refuses either override. The lit-output inventory does not establish display power-save support. Unassociated legacy ACPI backlights retain the existing global helper; they do not establish this interface's capability. A VM with an actually empty kernel inventory must report false. Harmless dimming disable and negative automatic-target reset succeed without eligible hardware. Positive unsupported operations fail. Nonfinite targets are explicitly refused by this bounded adapter; upstream JavaScript does not define the same explicit error contract.

The associated controller shares user intent across UI, keys and policy calls. Normalized zero maps to max(1, max_brightness / 100), except actual raw backlights with max_brightness <99 use minimum zero, matching GNOME51's small-range hardware rule. Values interpolate through the usable range. Global controls preserve monitor ratios, including when all values are zero during the same controller lifetime. Dimming clips the effective level to the live installed idle-brightness setting. Automatic brightness uses the GNOME user-bias formula. Disabling either policy restores the user baseline after exact actual readback. Policy changes do not emit a user-update signal. External hardware changes cancel dimming before subsequent policy derivation.

The installed session requires GNOME Settings Daemon's power schemas for idle-brightness and policy updates (gnome-settings-daemon-common on Debian, gnome-settings-daemon on Arch). These are runtime package dependencies; the controlled proof uses the same installed schema rather than a private substitute.

Each hardware transaction uses asynchronous logind calls with a two-second call bound and exact device, range, output-membership and post-call readback checks. Partial writes and refusals return failure; requested percentages are never presented as observed values. Concurrent user requests are refused while an owned transaction is pending; live idle-key changes coalesce to the latest value and apply after completion. Individual backlight scalar reads and the inventory are bounded; rejected inventory preserves the user baseline while withholding capability. This does not claim blocking filesystem metadata calls have a real-time deadline.

G-BRIGHTNESS-CONTRACT exercises the real session-bus adapter against an explicitly synthetic associated sysfs/logind fixture: user baseline, dim/restore, automatic bias/reset, live idle-key mutation/restoration, refused writes, exact readback mismatch, nonfinite rejection and no policy user-update signals. V-BRIGHTNESS-CONTRACT uses the actual native VM kernel inventory and original shell owner PID/UID/start identity, requiring empty inventory, false capability, unsupported positive operations and successful harmless resets. Neither proves real panel luminance or physical logind permissions.

At the controlled post-idle-brightness restore boundary, sysfs readback can precede completion of the owned asynchronous logind transaction. The proof retries only the exact side-effect-free brightness update already pending refusal, pacing attempts by up to 50ms within the same five-second absolute deadline and 100-attempt cap. Every attempt keeps principal/signal verification and its receipt; unrelated errors fail immediately and accepted operations are never repeated. This admission pacing changes no device policy or assertion.

Display power saving is the compositor's: DisplayConfig PowerSaveMode follows Mutter 51 (crates/compositor/src/power_save.rs). gsd's blank (3) stops scanout and turns every CRTC off on hardware; its unblank (0) repaints and modesets back; -1 is ignored. G-POWER-SAVE-MODE drives gsd 51's dim → blank → unblank → undim sequence in the nested proof: the dim lowers the controlled backlight, the blank stops frames while the pointer moves, the unblank repaints and the undim restores the exact user baseline.

The power-save proof waits for an in-flight idle-brightness transaction before both dimming and undimming. Only a brightness update already pending refusal permits another admission attempt, within the existing ten-second bound. Other errors fail immediately; an accepted call must still complete its own transaction and satisfy the unchanged backlight and scanout assertions.

Issue #355 remains open for physical hardware, connector association on other backlight topologies, persistence across shell restart, cloned-monitor policy, ambient sensor integration, the hardware CRTC disable, a session gnome-settings-daemon power plugin (idle/suspend and battery/AC policy), external service and shipped-image qualification. Two adapter behaviors differ from GNOME Shell 51 and stay open: idle-brightness is followed live (GNOME reads it once when the shell starts) and positive operations fail without an associated backlight (GNOME accepts them).

Primary contracts and formulas: GNOME Shell 51.0 org.gnome.Shell.Brightness.xml, brightnessManager.js, shellDBus.js, GNOME Settings 51.0 cc-power-panel.c, GNOME Settings Daemon 51.0 gsd-power-manager.c, and Mutter 51.0 org.gnome.Mutter.DisplayConfig.xml, meta-monitor-manager.c, meta-monitor-manager-native.c and meta-renderer-native.c.

Protocol: control protocol 0.37 appends NativeOutputInventory after the existing messages without changing OutputInfo or earlier indices. A peer advertising a minor below 37 receives no native inventory and cannot derive exact native backlight capability. The shared tuna-backlight crate holds the bounded sysfs reads (inventory, scalar, readback, connector identity). The default requested-level sysfs readback is distinct from optional hardware-reported actual_brightness; no panel luminance claim.