Disciplines · Decisions (ADRs)

ADR-0079: Eve native desktop fixture boundary

Browser automation cannot prove that Eve can capture pixels or deliver input through an operating-system desktop API.

4sections3 minread
Markdown source
On this page
  • Status: accepted for Task 6.4 evidence
  • Date: 2026-09-08
  • Owners: Eve computer-use, Security, host provisioning, Evaluation
  • Scope: Phase 6 Task 6.4 only

Context#

Browser automation cannot prove that Eve can capture pixels or deliver input through an operating-system desktop API. The pre-existing Iris native backend had unit coverage, but it did not have a reproducible graphical target, permission preflight, independently observable end state, or artifact cleanup proof. Its ESM loader also attempted to load native addons with dynamic import, which Node rejects for .node files, and the X11 display inventory hard-coded a 1x scale factor.

Task 6.4 needs a test target that cannot be confused with Playwright or with the quarantined simulated desktop prototype. It must also avoid treating successful native API return values as sufficient proof: the target application must record the file, clipboard, and final-state facts it observed.

Decision#

Adopt a browser-independent native fixture with these boundaries:

  1. The evidence runner creates a private scratch directory and a dedicated Xvfb server with TCP disabled, two X screens, and 144-DPI geometry. It never attaches to a member's existing display.
  2. A GTK3 target exposes a fixed-title window, controlled input and result files, a controlled X11 clipboard value, a visible state anchor, and a declared sensitive-pixel region. A second GTK3 process paints the second display. Neither process embeds a browser.
  3. The runner uses the production OshunDesktopController over the compiled Rust/N-API X11 backend. Native capture must distinguish both displays and report their measured non-1x scale factors.
  4. Before input, a separate AT-SPI client on the isolated D-Bus session must find the exact window, text entry, and commit button. Missing service access or any unmatched node blocks the run.
  5. A deliberate top-level occluder must hide the target anchor. The harness must detect that state and refuse input. Input may proceed only after the occluder exits and a newly captured frame proves that the anchor is visible again.
  6. The controlled transaction is mouse focus, native Ctrl+V, and mouse commit. Success requires application-side hashes for the source file, pasted text, and current clipboard to match the harness's expected hashes.
  7. Raw captured pixels stay in memory. Before any screenshot is written, every declared sensitive region is overwritten. The resulting PNG is mode 0600, has a zero-millisecond fixture retention policy, is deleted during the run, and is represented in retained evidence only by byte count and SHA-256.
  8. Cleanup terminates every fixture process and the X server, removes the X socket, and removes the private scratch directory. A missing cleanup fact fails the receipt verifier.

The native loader now accepts an explicit OSHUN_IRIS_DESKTOP_NATIVE_PATH for controlled local/CI builds and uses Node's native-addon require loader. Packaged platform addons remain the normal first party distribution path. X11 display scale is derived from pixel and physical millimetre geometry rather than hard-coded.

Evidence and refusal semantics#

The committed receipt contains runtime versions, native-addon hash, display inventory, accessibility results, capture hashes, action sequence, target-side result hashes, redaction counts, retention outcome, cleanup outcome, and hashes of the source files that define the fixture. It contains no screenshot bytes, raw clipboard value, raw controlled-file content, or reusable display socket.

The verifier rejects browser substitution, missing native capabilities, single-display or 1x-only evidence, failed accessibility matching, missing occlusion refusal/recovery, target-side transaction mismatches, raw-pixel persistence, a retained screenshot after expiry, incomplete process/socket/file cleanup, stale source hashes, and any claim that Task 6.4 closes Phase 6.

Consequences and honest boundary#

This establishes a dated, repeatable OS-level first-light harness on Linux X11. It does not prove Wayland portal behavior, macOS TCC, Windows UIA/UIPI, physical monitor characteristics, or member-desktop safety. Native clipboard methods on the Rust X11 binding also remain unavailable: the fixture owns the real X11 clipboard through GTK, proves that native Ctrl+V reaches the target, and checks the clipboard again inside the target.

Task 6.4 does not admit native computer use. Task 6.5 still owns run authority, focus and stale-frame controls, budgets, confirmation, and interruption; Task 6.6 owns admission; Task 6.7 owns benchmark breadth; Task 6.8 owns injection negatives. Phase 6 and G6/G10/G14 remain open.