{"row":{"id":"ADR-083","title":"L1 computer-use effect crates · cross-platform doctrine (macOS + Linux prio · Windows + all)","file":"adr-083-l1-computer-use-cross-platform-doctrine.md","status":"accepted","date":"2026-05-26","cites":4,"supersedes":[],"superseded_by":[],"layers":["L1"],"tags":["l1","computer-use","cross-platform","macos"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-083 · L1 computer-use effect crates · cross-platform doctrine","id":"adr-083--l1-computer-use-effect-crates--cross-platform-doctrine"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"The Phase 2 M2 computer-use L1 effect crates ("},{"k":"code","text":"nika-screen"},{"k":"text","text":" · "},{"k":"code","text":"nika-ocr"},{"k":"text","text":" ·\n"},{"k":"code","text":"nika-a11y"},{"k":"text","text":" · "},{"k":"code","text":"nika-input"},{"k":"text","text":" · "},{"k":"code","text":"nika-browser"},{"k":"text","text":" · "},{"k":"code","text":"nika-vision-local"},{"k":"text","text":") back the\nfuture "},{"k":"code","text":"invoke:"},{"k":"text","text":"-tool surface that lets a workflow "},{"k":"em","text":"see + act on"},{"k":"text","text":" a desktop."}]},{"k":"p","inline":[{"k":"text","text":"An empirical audit (2026-05-26) of the three already-admitted crates surfaced\nan "},{"k":"strong","text":"inconsistent platform posture"},{"k":"text","text":" that was never an explicit decision:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Crate · Backend · Platform reality"}],[{"k":"text","text":"`nika-screen` · `xcap` 0.9 · **cross-platform** (macOS / Linux / Windows)"}],[{"k":"text","text":"`nika-ocr` · `ocrs` + `rten` · **cross-platform** (pure-Rust, no target gate)"}],[{"k":"text","text":"`nika-a11y` · `accessibility` 0.2 · **macOS-only** (`[target.'cfg(target_os=\"macos\")']`)"}]]},{"k":"p","inline":[{"k":"code","text":"nika-screen"},{"k":"text","text":" and "},{"k":"code","text":"nika-ocr"},{"k":"text","text":" are cross-platform-by-default; "},{"k":"code","text":"nika-a11y"},{"k":"text","text":" shipped\nmacOS-only — "},{"k":"strong","text":"forced"},{"k":"text","text":", because no single cross-platform pure-Rust "},{"k":"em","text":"accessibility-\nquery"},{"k":"text","text":" crate exists ("},{"k":"code","text":"atspi"},{"k":"text","text":" = Linux AT-SPI2 · "},{"k":"code","text":"uiautomation"},{"k":"text","text":" = Windows UIA are\nper-OS). The macOS-only posture was a "},{"k":"em","text":"necessity"},{"k":"text","text":", not a chosen strategy — but it\nwas never written down as such, so the next crate ("},{"k":"code","text":"nika-input"},{"k":"text","text":", M2.4) nearly\ninherited \"macOS-first\" as if it were the pattern. It is not: "},{"k":"code","text":"nika-input"},{"k":"text","text":" has a\nmature cross-platform option ("},{"k":"code","text":"enigo"},{"k":"text","text":")."}]},{"k":"p","inline":[{"k":"text","text":"Operator directive (2026-05-26, verbatim): "},{"k":"em","text":"« je veux cette philosophie de cross\nplateform et macos, linux prio sous unix et aussi windows et tout les systeme …\non peut revoir et refactor a11y si besoin »"},{"k":"text","text":"."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"L1 computer-use effect crates are CROSS-PLATFORM."},{"k":"text","text":" Priority order ·\n"},{"k":"strong","text":"macOS + Linux (Unix family) first"},{"k":"text","text":", then "},{"k":"strong","text":"Windows"},{"k":"text","text":", then all systems."}]},{"k":"p","inline":[{"k":"strong","text":"Backend-selection rule (the doctrine):"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"Prefer "},{"k":"strong","text":"one mature, permissively-licensed cross-platform Rust crate"},{"k":"text","text":" that\ncovers macOS + Linux (+ Windows) behind the L0.5 trait. The guards (ADR-081)\nstay pure + at "},{"k":"em","text":"our"},{"k":"text","text":" layer, so a third-party backend never touches them."}],[{"k":"strong","text":"Only when no cross-platform crate exists"},{"k":"text","text":", fall back to "},{"k":"strong","text":"per-OS backends\nbehind the same L0.5 trait"},{"k":"text","text":" — and even then, macOS-only is a "},{"k":"em","text":"temporary"},{"k":"text","text":"\nstate: the Linux (then Windows) backends are a "},{"k":"strong","text":"planned refactor"},{"k":"text","text":", not a\npermanent gate. Prioritize the "},{"k":"strong","text":"macOS + Linux"},{"k":"text","text":" backends first."}],[{"k":"text","text":"The cross-platform DTOs + the mandatory guards always ship "},{"k":"strong","text":"all-OS, headless"},{"k":"text","text":"\n(a denied/unavailable OS returns "},{"k":"code","text":"BackendUnavailable"},{"k":"text","text":", never a compile gap in\nthe shared logic)."}]]},{"k":"h","depth":3,"text":"Per-crate disposition","id":"per-crate-disposition"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Crate · Disposition under this doctrine"}],[{"k":"text","text":"`nika-screen` · ✅ cross-platform already (`xcap`) · no action"}],[{"k":"text","text":"`nika-ocr` · ✅ cross-platform already (`ocrs`/`rten`) · no action"}],[{"k":"text","text":"`nika-a11y` · 🔧 **REFACTOR** · keep `accessibility` (macOS) · **add `atspi`** (Linux AT-SPI2 · the crate-spec §4 already vetted it · Apache/MIT) · `uiautomation` (Windows) later. Trait + `AxNode` DTO + Guard 3 are already backend-agnostic → additive per-OS backend behind `#[cfg]`. Amends the crate-spec's \"RESOLVED macOS-first\" disposition."}],[{"k":"text","text":"`nika-input` · 🆕 **cross-platform from day 1** via `enigo` (macOS + Linux + Windows · MIT). Resolves the M2.4 backend DECISION POINT. Guards 1+2 are pure + at our layer · `enigo` only performs the final OS event post. (No `enigo` is rejected in favour of macOS-only CGEvent — that would re-introduce the inconsistency this ADR removes.)"}],[{"k":"text","text":"`nika-browser` (M2.5) · cross-platform backend mandatory (the chosen automation lib must cover macOS + Linux)."}],[{"k":"text","text":"`nika-vision-local` (M2.6) · cross-platform by construction (local model inference · pure compute · like `nika-ocr`)."}]]},{"k":"p","inline":[{"k":"text","text":"Per-crate exact crate + symbol surface is "},{"k":"strong","text":"primary-source verified at Gate 3"},{"k":"text","text":"\n("},{"k":"code","text":".crate"},{"k":"text","text":" tarball extraction · the rigor that confirmed "},{"k":"code","text":"accessibility"},{"k":"text","text":" for\n"},{"k":"code","text":"nika-a11y"},{"k":"text","text":" · no phantom symbols written before verification)."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"One coherent platform posture across the computer-use cohort · no accidental\nmacOS lock-in."}],[{"k":"text","text":"macOS + Linux ship together (the operator's stated priority · Unix-family first)."}],[{"k":"text","text":"The guards stay backend-agnostic · adding an OS backend never touches security\nlogic."}]]},{"k":"h","depth":3,"text":"Negative (acknowledged · mitigated)","id":"negative-acknowledged--mitigated"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-a11y"},{"k":"text","text":" gains a Linux "},{"k":"code","text":"atspi"},{"k":"text","text":" backend (D-Bus/zbus) → a refactor + its own\nGate 3 primary-source verification + tri-platform consideration. Mitigated ·\nadditive behind the existing trait · the DTO + Guard 3 already all-OS."}],[{"k":"code","text":"nika-input"},{"k":"text","text":" takes a dependency on "},{"k":"code","text":"enigo"},{"k":"text","text":" (a backend we don't fully own) vs\nhand-written per-OS FFI. Mitigated · "},{"k":"code","text":"enigo"},{"k":"text","text":" is mature + permissive · the\nguards + consent type-state are "},{"k":"em","text":"ours"},{"k":"text","text":" (the dep only posts the final event)."}],[{"k":"text","text":"CI eventually wants macOS + Linux runners for the per-OS backends. Deferred ·\nheadless logic + guards are CI-covered all-OS today; real-OS smoke stays\n"},{"k":"code","text":"#[ignore]"},{"k":"text","text":" per the M2 precedent."}]]},{"k":"h","depth":3,"text":"Sequencing note (NOT this ADR's call · gate-review)","id":"sequencing-note-not-this-adrs-call--gate-review"},{"k":"p","inline":[{"k":"text","text":"The computer-use cohort is "},{"k":"strong","text":"not"},{"k":"text","text":" in the v0.81 first-publish scope (v0.81 =\nbinary engine + language · the 4 verbs + DAG + providers + MCP server). This ADR\ngoverns "},{"k":"strong","text":"how"},{"k":"text","text":" computer-use is built (cross-platform); "},{"k":"strong","text":"when"},{"k":"text","text":" (relative to the\nv0.81 spine: providers → verbs → L3 runtime) is an operator gate-review decision\ntracked separately (private roadmap)."}]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"macOS-first, port later (rejected)"},{"k":"text","text":" · the prior implicit posture. Rejected\nper operator directive — cross-platform is the "},{"k":"em","text":"philosophy"},{"k":"text","text":", day-1 where a\ncrate exists. macOS-only survives "},{"k":"em","text":"only"},{"k":"text","text":" where no cross-platform crate exists\n(a11y), as a temporary refactor target."}],[{"k":"strong","text":"`enigo` rejected for \"control\" (rejected)"},{"k":"text","text":" · the M2.4 spec's first draft\nleaned macOS-CGEvent for sovereignty/control. Re-examined · the guards are pure"},{"k":"text","text":"+ at our layer, so `enigo` does not weaken them · it only removes hand-written\nper-OS FFI. Cross-platform day-1 > marginal FFI ownership."}]]},{"k":"h","depth":2,"text":"References","id":"references"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"docs/crate-specs/nika-input.md"},{"k":"text","text":" §4 (backend DECISION POINT · resolved here)"}],[{"k":"code","text":"docs/crate-specs/nika-a11y.md"},{"k":"text","text":" §4 (macOS-first disposition · amended here)"}],[{"k":"code","text":"docs/adr/adr-081-l1-effect-crate-guard-contract.md"},{"k":"text","text":" (guard contract · backend-agnostic)"}],[{"k":"code","text":"crates/nika-kernel-core/src/io/input.rs"},{"k":"text","text":" (the trait names macOS CGEvent · Windows SendInput · Linux uinput — superseded for "},{"k":"code","text":"nika-input"},{"k":"text","text":" by the cross-platform "},{"k":"code","text":"enigo"},{"k":"text","text":" choice; the per-OS APIs remain the fallback model the trait doc describes)"}],[{"k":"text","text":"v0.81 first-publish scope (binary engine + language · the 4 verbs + DAG + providers + MCP server) · sequencing context for the §Sequencing note (private roadmap · not cited from this public repo)"}]]},{"k":"h","depth":2,"text":"Update log","id":"update-log"},{"k":"code","lang":"text","text":"2026-05-26  ACCEPTED — initial · operator directive locks the cross-platform\n              doctrine for the L1 computer-use cohort (macOS + Linux prio ·\n              Windows + all). Resolves nika-input backend = enigo (cross-platform\n              day-1). Flags nika-a11y for a Linux atspi backend refactor. screen +\n              ocr already cross-platform (no action). Guards stay backend-agnostic.\n              Sequencing (now vs v0.81 spine) is a separate operator gate-review."}]

ADR-083

L1 computer-use effect crates · cross-platform doctrine (macOS + Linux prio · Windows + all)

accepted · 2026-05-26 · L1 · cites 4

ADR-083 · L1 computer-use effect crates · cross-platform doctrine #

Context #

The Phase 2 M2 computer-use L1 effect crates (nika-screen · nika-ocr · nika-a11y · nika-input · nika-browser · nika-vision-local) back the future invoke:-tool surface that lets a workflow see + act on a desktop.

An empirical audit (2026-05-26) of the three already-admitted crates surfaced an inconsistent platform posture that was never an explicit decision:

Crate · Backend · Platform reality
`nika-screen` · `xcap` 0.9 · **cross-platform** (macOS / Linux / Windows)
`nika-ocr` · `ocrs` + `rten` · **cross-platform** (pure-Rust, no target gate)
`nika-a11y` · `accessibility` 0.2 · **macOS-only** (`[target.'cfg(target_os="macos")']`)

nika-screen and nika-ocr are cross-platform-by-default; nika-a11y shipped macOS-only — forced, because no single cross-platform pure-Rust accessibility- query crate exists (atspi = Linux AT-SPI2 · uiautomation = Windows UIA are per-OS). The macOS-only posture was a necessity, not a chosen strategy — but it was never written down as such, so the next crate (nika-input, M2.4) nearly inherited "macOS-first" as if it were the pattern. It is not: nika-input has a mature cross-platform option (enigo).

Operator directive (2026-05-26, verbatim): « je veux cette philosophie de cross plateform et macos, linux prio sous unix et aussi windows et tout les systeme … on peut revoir et refactor a11y si besoin ».

Decision #

L1 computer-use effect crates are CROSS-PLATFORM. Priority order · macOS + Linux (Unix family) first, then Windows, then all systems.

Backend-selection rule (the doctrine):

Prefer one mature, permissively-licensed cross-platform Rust crate that covers macOS + Linux (+ Windows) behind the L0.5 trait. The guards (ADR-081) stay pure + at our layer, so a third-party backend never touches them.
Only when no cross-platform crate exists, fall back to per-OS backends behind the same L0.5 trait — and even then, macOS-only is a temporary state: the Linux (then Windows) backends are a planned refactor, not a permanent gate. Prioritize the macOS + Linux backends first.
The cross-platform DTOs + the mandatory guards always ship all-OS, headless (a denied/unavailable OS returns BackendUnavailable, never a compile gap in the shared logic).

Per-crate disposition #

Crate · Disposition under this doctrine
`nika-screen` · ✅ cross-platform already (`xcap`) · no action
`nika-ocr` · ✅ cross-platform already (`ocrs`/`rten`) · no action
`nika-a11y` · 🔧 **REFACTOR** · keep `accessibility` (macOS) · **add `atspi`** (Linux AT-SPI2 · the crate-spec §4 already vetted it · Apache/MIT) · `uiautomation` (Windows) later. Trait + `AxNode` DTO + Guard 3 are already backend-agnostic → additive per-OS backend behind `#[cfg]`. Amends the crate-spec's "RESOLVED macOS-first" disposition.
`nika-input` · 🆕 **cross-platform from day 1** via `enigo` (macOS + Linux + Windows · MIT). Resolves the M2.4 backend DECISION POINT. Guards 1+2 are pure + at our layer · `enigo` only performs the final OS event post. (No `enigo` is rejected in favour of macOS-only CGEvent — that would re-introduce the inconsistency this ADR removes.)
`nika-browser` (M2.5) · cross-platform backend mandatory (the chosen automation lib must cover macOS + Linux).
`nika-vision-local` (M2.6) · cross-platform by construction (local model inference · pure compute · like `nika-ocr`).

Per-crate exact crate + symbol surface is primary-source verified at Gate 3 (.crate tarball extraction · the rigor that confirmed accessibility for nika-a11y · no phantom symbols written before verification).

Consequences #

Positive #

One coherent platform posture across the computer-use cohort · no accidental macOS lock-in.
macOS + Linux ship together (the operator's stated priority · Unix-family first).
The guards stay backend-agnostic · adding an OS backend never touches security logic.

Negative (acknowledged · mitigated) #

nika-a11y gains a Linux atspi backend (D-Bus/zbus) → a refactor + its own Gate 3 primary-source verification + tri-platform consideration. Mitigated · additive behind the existing trait · the DTO + Guard 3 already all-OS.
nika-input takes a dependency on enigo (a backend we don't fully own) vs hand-written per-OS FFI. Mitigated · enigo is mature + permissive · the guards + consent type-state are ours (the dep only posts the final event).
CI eventually wants macOS + Linux runners for the per-OS backends. Deferred · headless logic + guards are CI-covered all-OS today; real-OS smoke stays #[ignore] per the M2 precedent.

Sequencing note (NOT this ADR's call · gate-review) #

The computer-use cohort is not in the v0.81 first-publish scope (v0.81 = binary engine + language · the 4 verbs + DAG + providers + MCP server). This ADR governs how computer-use is built (cross-platform); when (relative to the v0.81 spine: providers → verbs → L3 runtime) is an operator gate-review decision tracked separately (private roadmap).

Alternatives considered #

macOS-first, port later (rejected) · the prior implicit posture. Rejected per operator directive — cross-platform is the philosophy, day-1 where a crate exists. macOS-only survives only where no cross-platform crate exists (a11y), as a temporary refactor target.
`enigo` rejected for "control" (rejected) · the M2.4 spec's first draft leaned macOS-CGEvent for sovereignty/control. Re-examined · the guards are pure+ at our layer, so `enigo` does not weaken them · it only removes hand-written per-OS FFI. Cross-platform day-1 > marginal FFI ownership.

References #

docs/crate-specs/nika-input.md §4 (backend DECISION POINT · resolved here)
docs/crate-specs/nika-a11y.md §4 (macOS-first disposition · amended here)
docs/adr/adr-081-l1-effect-crate-guard-contract.md (guard contract · backend-agnostic)
crates/nika-kernel-core/src/io/input.rs (the trait names macOS CGEvent · Windows SendInput · Linux uinput — superseded for nika-input by the cross-platform enigo choice; the per-OS APIs remain the fallback model the trait doc describes)
v0.81 first-publish scope (binary engine + language · the 4 verbs + DAG + providers + MCP server) · sequencing context for the §Sequencing note (private roadmap · not cited from this public repo)

Update log #

text

12026-05-26  ACCEPTED — initial · operator directive locks the cross-platform2              doctrine for the L1 computer-use cohort (macOS + Linux prio ·3              Windows + all). Resolves nika-input backend = enigo (cross-platform4              day-1). Flags nika-a11y for a Linux atspi backend refactor. screen +5              ocr already cross-platform (no action). Guards stay backend-agnostic.6              Sequencing (now vs v0.81 spine) is a separate operator gate-review.

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo