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#
- Phase 180 ground rules and
ADR-0001are authoritative for security and architecture boundaries. - Current repo configuration is authoritative for monorepo tooling:
package.json,pnpm-workspace.yaml, relevantpyproject.tomlfiles, Bellona domain docs, and audited bridge/runtime code. - 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.
- 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/