# Unreal Read-Only And Safe Mutation MVP Closure

Closure date: 2026-04-23

This note closes `180.C.15` for the Unreal read-only and first safe mutation
MVP. It records the evidence that Unreal commands now follow the same Bellona
Remote Creative Control Plane path used by Blender: protocol-owned schemas,
gateway policy and audit, Remote Host adapter routing, transaction/undo
metadata, evidence placeholders, and documented optional hardware smoke.

## Closure Scope

The closed command path is:

- read-only protocol commands: `unreal.project.info` and `unreal.world.query`
- first safe mutation protocol command: `unreal.actor.spawn`
- host adapter: `adapter:unreal-local`
- required mutation permission scope: `project.write`
- mutation risk class: `safe-mutation`
- rollback strategy: `undo_stack`
- mutation result fields: actor summary, object reference, editor transaction,
  undo checkpoint id, evidence references, and visual verification placeholder

This closure does not claim broad Unreal Editor control. It closes the Stage 15
MVP surface only: discovery, project info, world query, and a fixture-safe actor
spawn command with mocked editor transaction behavior and an optional hardware
smoke entry point.

## Implementation Evidence

The closed path is backed by the following completed Phase 180 items:

- `180.C.15.01`: Unreal plugin architecture, security boundary, command order,
  and Stage 15 gate documented.
- `180.C.15.02`: Unreal adapter discovery for engine, project, plugin, editor,
  Remote Control, and supported command state.
- `180.C.15.03`: protocol-owned `unreal.project.info` schema, fixture, and
  mocked adapter response.
- `180.C.15.04`: protocol-owned `unreal.world.query` schema, fixture, and mocked
  adapter response.
- `180.C.15.05`: editor-only Unreal plugin bundle plus authenticated
  localhost-only readiness transport.
- `180.C.15.06`: gateway-host routing for `unreal.project.info` and
  `unreal.world.query` with timeline and audit visibility.
- `180.C.15.07`: protocol, policy, host adapter, gateway routing, transaction,
  undo checkpoint, object reference, and evidence placeholder support for
  `unreal.actor.spawn`.
- `180.C.15.08`: mocked failure matrix for missing Unreal, missing plugin,
  project/editor not ready, successful read-only query, actor spawn, policy
  deny, and failed transaction results.
- `180.C.15.09`: optional fixture-project smoke command for read-only query and
  actor spawn, with structured skip behavior when hardware is not configured.

## Deterministic Remote Evidence

The read-only remote smoke validates the gateway-host-adapter path with
deterministic fixture-backed Unreal outputs:

```bash
pnpm nx unreal:readonly-remote-smoke @bellona/remote-host --skip-nx-cache --verbose
```

The actor-spawn fixture smoke validates the protocol output shape for
`unreal.project.info`, `unreal.world.query`, and `unreal.actor.spawn`, and exits
with a structured skip unless a fixture Unreal project is explicitly enabled:

```bash
pnpm nx unreal:actor-spawn-remote-smoke @bellona/remote-host --skip-nx-cache --verbose
```

Result on this machine:

```json
{
  "status": "skipped",
  "required": false,
  "reason": "Set BELLONA_UNREAL_HARDWARE_SMOKE=1 and BELLONA_UNREAL_PROJECT_PATH to run the optional Unreal fixture smoke."
}
```

The deterministic package tests also validate:

- protocol schema acceptance and rejection paths for Unreal commands
- policy scope inference and denial for `unreal.actor.spawn`
- adapter registration and observe-only mutation blocking
- read-only project/world query outputs
- actor-spawn transaction success and failure output
- gateway command dispatch, audit entries, timeline events, and client result
  routing

## Hardware Evidence Boundary

No live Unreal Editor process, compiled plugin binary loaded in an editor,
Remote Control endpoint, second MacBook, WebRTC stream, approval backend,
browser profile, desktop helper, Blender process, or cloud model was exercised
for this closure.

Live fixture evidence remains available through:

```bash
BELLONA_UNREAL_HARDWARE_SMOKE=1 \
BELLONA_UNREAL_PROJECT_PATH=/path/to/FixtureProject.uproject \
pnpm nx unreal:actor-spawn-remote-smoke @bellona/remote-host -- --required
```

When hardware is configured, the smoke records project path, plugin descriptor,
plugin connection status, editor process id, command ids, actor id, transaction
id, undo checkpoint id, screenshot placeholder status, and whether a live editor
connection was exercised.

## Rollback Note For Review Records

For this closure, review records should attach the following note:

```json
{
  "commandId": "command:unreal-actor-spawn-fixture-smoke-001",
  "rollbackStrategy": "undo_stack",
  "undoCheckpointId": "undo-checkpoint:command:unreal-actor-spawn-fixture-smoke-001",
  "transactionStatus": "committed",
  "actorId": "actor:bellona-spawned-static-mesh-001",
  "objectReference": "actor:bellona-spawned-static-mesh-001",
  "visualVerification": "screenshot_placeholder",
  "rollbackAttempted": false,
  "rollbackResult": "documented_manual_editor_undo",
  "limitations": [
    "Stage 15 actor spawn uses mocked transaction output unless an Unreal fixture project is explicitly configured.",
    "Unreal undo stack validity is scoped to the active editor transaction history.",
    "The MVP does not expose a remote rollback command.",
    "Screenshot capture remains a placeholder until later visual evidence work replaces it."
  ]
}
```

## Closure Decision

`180.C.15` is closed for the Unreal read-only and safe mutation MVP because the
system now has:

- canonical protocol ownership for Unreal discovery, read-only query, and first
  safe mutation commands
- localhost-only plugin readiness transport and loopback validation
- Remote Host adapter registration, capability reporting, and observe-only
  mutation denial
- gateway policy, audit, timeline, and client result routing for read-only and
  safe mutation commands
- transaction and undo checkpoint metadata for the mutation result
- evidence references and screenshot placeholder status
- mocked success and failure coverage for the Stage 15 command surface
- optional hardware smoke entry point with explicit skip and required modes
- documented limitations for live editor, undo, and visual evidence

The next unchecked Phase 180 item is `180.C.16.01`, but this closure note does
not start that stage.
