# Bellona Remote Control Compatibility Matrix

Matrix date: 2026-04-21

This matrix records the compatibility target for Phase 180 remote-control work.
It is not a promise that all rows are implemented today. It separates
repo-proven baselines, implementation targets, candidate versions, and blocked
surfaces so gateway, host, adapter, MCP, and Control Room work can make explicit
support decisions.

## Status Legend

- **Baseline**: use for first implementation and automated contract tests.
- **Supported candidate**: may be enabled after compatibility tests and
  hardware/manual evidence.
- **Legacy**: existing docs/code mention it, but new privileged work should not
  start there unless a customer or fixture requires it.
- **Blocked**: must remain disabled until later policy, approval, audit, or
  hardware evidence exists.

## Source Hierarchy

1. Phase 180 ground rules and `ADR-0001` are authoritative for security and
   architecture boundaries.
2. Current repo configuration is authoritative for monorepo tooling:
   `package.json`, `pnpm-workspace.yaml`, relevant `pyproject.toml` files,
   Bellona domain docs, and audited bridge/runtime code.
3. Official upstream docs are used for current product lifecycle reality:
   Node.js releases, Blender LTS/release notes, Unreal Engine 5.6 release notes,
   Chrome remote debugging behavior, Playwright browser support, Apple
   capture/permission docs, and WebRTC ICE/STUN/TURN docs.
4. If repo docs and upstream docs conflict, Phase 180 implementation must use a
   conservative target and record the wider version as a candidate until tests
   prove it.

## Core Compatibility Matrix

| Surface              | MVP Baseline                                                                                                                                                                            | Candidate / Test Range                                                                                                                                                                            | Explicitly Blocked or Deferred                                                                                                                                                                                                                                                | Verification Required Before Checked Implementation                                                                                                                                                                                                            |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS remote host    | macOS 14 Sonoma on Apple Silicon for the controlled MacBook. This matches current Unreal requirements better than older desktop-shell docs and keeps host work aligned with modern TCC. | macOS 13 Ventura may remain a transitional operator-wrapper minimum because Yemaya Desktop docs already use macOS 13+. macOS 15 is a candidate for future HDR/SM6/advanced capture tests.         | Intel Macs are not an MVP host target. Unsigned helpers, background input, screen capture, browser profile access, and file grants are blocked until TCC prompts, signing/notarization, policy, approval, and audit are implemented.                                          | Hardware/manual evidence on a real Mac for Accessibility, Screen Recording, input injection, foreground app targeting, multi-display capture, sleep/wake reconnect, notarized helper startup, and uninstall/permission reset behavior.                         |
| Operator web/desktop | Browser-first Bellona Control Room consuming gateway APIs. Desktop wrapper is later distribution/native affordance only.                                                                | Electron wrapper can reuse Yemaya Desktop's Node 20+/pnpm 10/macOS 13+ build pattern after the web Control Room boundary exists.                                                                  | Renderer-owned privileged execution is blocked. Electron IPC cannot bypass gateway/host protocol, policy, approval, or audit.                                                                                                                                                 | Playwright desktop/mobile coverage for web UI states; Electron smoke/manual evidence later for native menus, deep links, multi-monitor/PiP, update/signing, and permission diagnostics.                                                                        |
| Blender adapter      | Blender 4.0.x for the first remote adapter because Bellona developer docs require `>=4.0` and repo docs list `3.6-4.0`. Host talks to the addon on localhost only.                      | Blender 4.2 LTS and 4.5 LTS are supported candidates. Blender 4.5 LTS is current upstream LTS and maintained until July 2027.                                                                     | Blender 3.6 is legacy/read-only unless a fixture requires it. Arbitrary Python, arbitrary file open/save, destructive deletes, render jobs, and import/export are blocked until path grants, policy, approvals, undo/evidence, and audit exist.                               | Vitest/schema adapter tests first, then hardware evidence in Blender for addon install/startup, `localhost:9876`, main-thread marshaling, safe read-only scene query, safe primitive mutation, timeout/cancel, crash/restart, and evidence capture.            |
| Unreal adapter       | Unreal Engine 5.3 for the first remote adapter because Bellona developer docs require `>=5.3` and repo docs list `5.0-5.3`.                                                             | Unreal 5.4, 5.5, and 5.6 are supported candidates after plugin/API compatibility tests. Upstream UE 5.6 uses macOS 14 and Xcode 16 baselines.                                                     | Unreal 5.0-5.2 are legacy. Console commands, arbitrary Blueprint calls, destructive actor/level operations, and project file mutation are blocked until protocol schemas, policy, approvals, undo/evidence, and audit exist.                                                  | Vitest/schema adapter tests first, then hardware evidence in Unreal Editor for version discovery, project open, read-only world query, safe actor spawn in a fixture level, timeout/cancel, editor crash/restart, and screenshot/evidence capture.             |
| Chrome/Chromium/CDP  | Playwright-managed Chromium for automated tests and isolated automation profiles. Any CDP endpoint remains localhost-only on the host.                                                  | Branded Google Chrome Stable/Beta through Playwright channels or Chrome for Testing after media-codec and policy checks.                                                                          | Real user profiles are blocked. Chrome remote debugging against the default profile is blocked; Chrome 136+ requires a non-default `--user-data-dir` for remote debugging switches. Credential/cookie extraction is blocked until the threat model and policy gates allow it. | Playwright tests with isolated profiles; adapter tests for tab/page/query commands; manual evidence for real Chrome app control, custom user-data-dir, browser crash/restart, download/upload path grants, redaction, and malicious-page containment.          |
| Node.js runtime      | Root monorepo baseline is Node.js `>=20.0.0` with pnpm pinned to `10.25.0`. New Phase 180 TypeScript packages should target Node 22 LTS first while staying compatible with Node 20.    | Node 24 Active LTS should be added to CI once gateway/host packages exist. Node 20 and 22 are Maintenance LTS lines in the current upstream release table.                                        | Node 18 is not a Phase 180 target even though one older Bellona library declares `>=18.0.0`; the repo root requirement supersedes it for new work. Odd-numbered Current releases are not production baselines.                                                                | Package build/typecheck/test on the selected CI Node matrix; WebSocket/WebRTC signaling tests; durable storage/client compatibility tests when gateway packages exist.                                                                                         |
| Python runtime       | Python 3.11 for Psyche fallback reuse because audited Psyche services use `python = "^3.11"` and ruff/mypy target `py311`.                                                              | Python 3.12 and 3.13 are migration candidates after OpenCV, OCR, aiortc, av, Playwright, and macOS native helper compatibility is proven.                                                         | Python 3.10 and older are not new remote-host targets. Packaging-tool migration from Poetry to uv is out of scope for this matrix and must be handled as a separate repo-wide tooling task.                                                                                   | Existing Psyche lint/test commands for reused code, plus future fallback-library unit tests across screenshot, OCR, accessibility, input, browser, file, and streaming extras. Hardware evidence on macOS is required before any fallback provider is checked. |
| WebRTC media/data    | Gateway-authorized signaling first; media streams are disabled by default until policy/audit and hardware evidence exist. Control commands must not depend on media success.            | Same-LAN direct ICE candidates are candidates after signaling tests. Cloud mode requires TURN for reliable cross-NAT relay. Psyche's optional `aiortc`/`av` extras are implementation references. | Browser-to-host direct unauthenticated media, unaudited screen sharing, default-open UDP ranges, and media paths that bypass gateway session authorization are blocked.                                                                                                       | Contract tests for signaling envelopes; network impairment tests for reconnect/backpressure; manual evidence for same-LAN and cross-network ICE/STUN/TURN, degraded state, bitrate/fps adaptation, consent/permission UI, stream redaction, and teardown.      |
| Same-LAN mode        | Gateway may run on the primary MacBook or another trusted LAN node. Remote Host connects outbound over authenticated WebSocket/WSS. Engine/browser/debug ports stay localhost-only.     | LAN service discovery is a candidate after pairing/auth exists; until then, explicit gateway URL or pairing code is safer.                                                                        | Host inbound command ports and direct LAN exposure of Blender/Unreal/CDP/desktop control are blocked.                                                                                                                                                                         | Fake gateway/host contract tests, then two-Mac manual evidence for pairing, reconnect, offline/degraded state, command round trip, local stream path, and emergency stop.                                                                                      |
| Cloud gateway mode   | Gateway runs in trusted cloud or LAN-cloud edge; Host connects outbound over WSS 443; Control Room/MCP clients use HTTPS/WSS to gateway.                                                | Hetzner and AWS are candidate deployment targets. TURN is required for reliable cross-network media; direct peer paths are optimization only.                                                     | Any design requiring inbound ports on the controlled MacBook is blocked. Production cloud gateway using memory-only session/command/audit state is blocked.                                                                                                                   | Integration tests against fake host and fake client; persistence/audit tests; deployment smoke tests; manual evidence for cross-network host reconnect, TURN relay, command latency, stream degradation, gateway restart, and audit replay.                    |

## Version Baselines by Component

| Component / Runtime          | Repo Evidence                                                                                                                                                                                                                                                                      | Phase 180 Target                                                                                           | Notes                                                                                                                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Monorepo package manager     | `package.json` pins `packageManager` to `pnpm@10.25.0`; root engines allow `pnpm >=10.0.0`.                                                                                                                                                                                        | Use pnpm 10.x for Phase 180 commits.                                                                       | Do not introduce npm/yarn lockfiles.                                                                                                                                                                       |
| TypeScript                   | Root `package.json` uses `typescript ^6.0.3`, root `tsconfig.base.json` has no `ignoreDeprecations` override, Nx `22.7.4`, Vite catalog `^8.0.14`, Vitest `^4.1.7`. Known nested package-internal TypeScript 5 compilers are disclosed and constrained by `pnpm verify:phase 180`. | Use existing Nx/Vite/Vitest patterns for new TS packages and keep Phase 180 typecheck targets on TS6.      | Protocol schemas should include drift checks before implementation packages depend on them; checked-in Bellona Remote targets must not rely on CLI or inherited tsconfig compiler deprecation workarounds. |
| Python service tooling       | Psyche services currently use Poetry pyprojects and Poetry-backed Nx targets.                                                                                                                                                                                                      | Keep existing Poetry verification until a separate uv migration is explicitly scoped and verified.         | Runtime target is Python 3.11; package-manager modernization must not be mixed into privileged remote-control implementation without a plan.                                                               |
| Bellona engine bridge docs   | Bellona docs list Blender `3.6-4.0`, Unreal `5.0-5.3`; developer guide lists Blender `>=4.0`, Unreal `>=5.3`.                                                                                                                                                                      | Start adapter implementation at Blender 4.0 and Unreal 5.3, then expand to LTS/current candidates.         | The matrix intentionally narrows initial targets to avoid overclaiming support from stale docs.                                                                                                            |
| Blender addon runtime        | Audited addon defaults to `localhost:9876`, uses Blender `bpy`, handlers, timers, and main-thread marshaling.                                                                                                                                                                      | Host adapter talks to addon over localhost only and records Blender version/capability metadata.           | External Python dependencies cannot be assumed inside Blender's embedded interpreter.                                                                                                                      |
| Bellona bridge-core          | Audited bridge-core has lifecycle, heartbeat, request/response, reconnect, and validation precedents.                                                                                                                                                                              | Reuse patterns but not wire contracts; Phase 180 contracts come from `libs/bellona/remote-protocol`.       | Existing bridge ports such as `9001` and `9003` remain local adapter concerns, not LAN/cloud surfaces.                                                                                                     |
| Psyche computer-use fallback | Pyproject uses Python 3.11 and optional OCR, Playwright, `aiortc`, `av`, Docker, database, and cache extras.                                                                                                                                                                       | Extract primitives later into `libs/psyche/desktop-fallback`; keep fallback subordinate to typed adapters. | Existing Linux/Xvfb assumptions must be replaced or wrapped for macOS TCC, ScreenCaptureKit/CG capture, Accessibility, and native input.                                                                   |
| Browser automation           | Repo uses Playwright in TS and Python; `studio-web` already has Playwright coverage.                                                                                                                                                                                               | Use Playwright Chromium for tests, isolated Chrome/Chromium profiles for host browser adapter work.        | CDP ports remain localhost-only; real profiles and credentials are blocked.                                                                                                                                |
| WebRTC                       | Psyche computer-use has optional `aiortc`/`av`; README describes H.264/VP9/AV1 streaming; MDN documents ICE use.                                                                                                                                                                   | Gateway signaling contracts first, then same-LAN/TURN media tests.                                         | TURN must be part of cloud gateway compatibility, not an optional production afterthought.                                                                                                                 |

## Network Mode Compatibility

| Mode            | Gateway Location                                                     | Host Connection                                        | Client / MCP Connection                     | Stream Path                                                                                      | Minimum Evidence Before Support                                                                                                                               |
| --------------- | -------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Same LAN        | Primary MacBook or trusted LAN machine.                              | Outbound authenticated WS/WSS from controlled MacBook. | HTTPS/WSS to LAN gateway.                   | Gateway-signaled WebRTC; direct LAN ICE candidates allowed only after auth and session approval. | Two-Mac test: pairing, command round trip, adapter capability report, stream start/stop, network drop/reconnect, audit record, emergency stop.                |
| Cloud gateway   | Hetzner/AWS/trusted cloud or an edge gateway reachable over WSS 443. | Outbound authenticated WSS 443; no inbound host port.  | HTTPS/WSS to cloud gateway.                 | TURN relay required for reliability; direct peer path is optimization only.                      | Cross-network test: host behind NAT, client on different network, TURN relay, gateway restart, host reconnect, audit replay, command latency/degraded states. |
| Offline fixture | Local fake gateway and fake host in test process or local ports.     | In-process or localhost-only fake transport.           | In-process/localhost fake client transport. | No real media; fixture stream descriptors and deterministic progress events.                     | Automated contract tests for validation failure, timeout, cancel, idempotency, disconnect, policy deny/allow, approval states, and audit emission.            |
| Direct adapter  | None.                                                                | Not permitted for remote-control production.           | Not permitted.                              | Not permitted.                                                                                   | Blocked by Phase 180 localhost adapter rule and `ADR-0001`; direct exposure of engine, browser, or desktop ports must not be implemented.                     |

## Implementation Gates

- Protocol schemas and fixtures must encode version/capability metadata for
  macOS, host runtime, gateway runtime, adapter kind, adapter version, engine
  version, browser version, Node version, Python version, WebRTC support, and
  network mode.
- Gateway and host handshakes must reject unsupported major protocol versions
  and report degraded candidate support rather than silently enabling it.
- Adapter capability reports must distinguish read-only, safe mutation,
  destructive mutation, file-system access, arbitrary script/console, render
  job, browser profile, desktop fallback, and stream capture permissions.
- CI can verify schema, gateway, host, and fake-adapter compatibility, but real
  macOS permissions, Blender, Unreal, Chrome app/profile behavior, WebRTC media,
  and two-network operation require hardware/manual evidence before the
  corresponding implementation item is checked.
- Any matrix expansion must update this file, the implementation tracker, and
  relevant tests before a new version or mode is advertised as supported.

## Upstream Source Anchors

Official external sources reviewed on 2026-04-21:

- Node.js release schedule: <https://nodejs.org/en/about/releases/>
- Blender 4.5 LTS release notes:
  <https://developer.blender.org/docs/release_notes/4.5/>
- Blender LTS support page: <https://www.blender.org/download/lts/>
- Unreal Engine 5.6 release notes:
  <https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-6-release-notes>
- Chrome remote debugging security change:
  <https://developer.chrome.com/blog/remote-debugging-port>
- Playwright browser support: <https://playwright.dev/docs/browsers>
- Apple ScreenCaptureKit screen capture docs:
  <https://developer.apple.com/documentation/screencapturekit/capturing_screen_content_in_macos>
- Apple media capture authorization docs:
  <https://developer.apple.com/documentation/bundleresources/requesting-authorization-for-media-capture-on-macos>
- WebRTC ICE/STUN/TURN overview:
  <https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Protocols>
- Python 3.11 release schedule: <https://peps.python.org/pep-0664/>
