# Blender Primitive Rollback And Undo

This note documents the rollback behavior for the Phase 180 safe mutation MVP:
`blender.object.create_primitive`.

It applies to the command path implemented through `180.C.10.08`:

- protocol command: `blender.object.create_primitive`
- host addon command: `object.create_primitive`
- rollback strategy: `undo_stack`
- required metadata: `metadata.rollbackStrategy: "undo_stack"`
- result field: `output.undoCheckpoint`
- evidence field: `output.evidenceReferences`

## What Happens Before Mutation

The Blender addon creates an undo checkpoint immediately before it calls the
Blender mesh primitive operator. The checkpoint is created by
`bpy.ops.ed.undo_push(message=...)` inside the addon helper
`_create_undo_checkpoint(...)`.

For primitive creation, the checkpoint label is:

```text
Bellona create primitive: <requested object name or primitive type>
```

The command result includes checkpoint metadata:

```json
{
  "undoCheckpoint": {
    "id": "undo-checkpoint:command:blender-create-primitive-remote-smoke-001",
    "label": "Bellona create primitive: Bellona Remote Mutation Cube",
    "createdAt": "2026-04-22T00:00:01.000Z",
    "rollbackStrategy": "undo_stack"
  }
}
```

The host also captures before/after scene-info evidence around the mutation. The
primitive result includes evidence references similar to:

```json
{
  "evidenceReferences": {
    "beforeSceneInfoArtifactId": "artifact:blender-create-primitive-001-before-scene-info",
    "afterSceneInfoArtifactId": "artifact:blender-create-primitive-001-after-scene-info",
    "beforeSceneInfoEvidenceId": "evidence:blender-create-primitive-001-before-scene-info",
    "afterSceneInfoEvidenceId": "evidence:blender-create-primitive-001-after-scene-info"
  }
}
```

## Operator Rollback Procedure

Use this procedure when a primitive creation command needs to be rolled back in
the current Blender session.

1. Locate the command result in the gateway timeline or CLI output.
2. Confirm the command result status is `succeeded`.
3. Confirm `output.undoCheckpoint.rollbackStrategy` is `undo_stack`.
4. Confirm the before/after scene-info evidence identifies exactly one newly
   created object.
5. In Blender, perform one normal undo operation from the active session.
6. Capture scene-info again and verify the created object id is no longer
   present.
7. Attach the rollback note to the command review record with the command id,
   undo checkpoint id, operator, timestamp, and post-undo scene-info evidence.

For a local manual verification run, the expected primitive smoke command is:

```bash
pnpm nx blender:create-primitive-smoke @bellona/remote-host -- --required
```

That smoke runs Blender in `--background` mode. Background mode can create the
primitive and verify scene-info changes, but it cannot exercise the editor undo
operator because there is no UI editor context. The smoke records that as a
rollback note and restores the saved fixture to prove the created object is
absent after cleanup. Active-session operator rollback is still the normal
Blender undo step described above.

The expected remote timeline visibility command is:

```bash
pnpm nx blender:create-primitive-remote-smoke @bellona/remote-host
```

The remote CLI should show:

- `auditEntryTypes` containing `command.received`, `command.dispatched`, and
  `command.completed`
- `timelineResult.resultStatus` equal to `succeeded`
- `mutationResult.undoCheckpointId` populated
- `mutationResult.evidenceReferenceCount` greater than zero

## Current Guarantees

The current MVP guarantees:

- Primitive command envelopes require `rollbackStrategy: "undo_stack"`.
- The addon creates the undo checkpoint before the primitive operator mutates
  the scene.
- The host rejects observe-only sessions before adapter routing.
- The host captures before/after scene-info evidence around successful primitive
  creation.
- The command result returns object identity, scene-info object id, undo
  checkpoint metadata, and evidence references.
- The CLI timeline smoke proves the command result is visible through the
  gateway command timeline before Control Room UI work.

## Limitations

The current MVP does not expose a remote rollback command. Rollback is a manual
operator action in the active Blender session.

Important limitations:

- Blender undo history is process-local and session-local. It is not durable
  across Blender restarts, file reloads, or undo stack clearing.
- If the operator or another tool mutates the scene after Bellona creates the
  primitive, the next undo may affect that later mutation first.
- The MVP does not pause the Blender UI or lock other addon clients while a
  command is running.
- The before/after scene-info artifacts prove the mutation result, but they are
  not a full scene snapshot that can restore arbitrary Blender state.
- Material, collection, and object naming collisions can make human review more
  complex even when the command result has a stable object id.
- Undo failure is surfaced as command failure when the addon cannot create the
  checkpoint, but partial host/gateway failures after mutation still require
  operator review of Blender scene state.
- Arbitrary Python rollback is intentionally not exposed through the remote
  command path in this MVP.

## Required Rollback Note

For `180.C.10.10` and later release-gate evidence, use this note shape:

```json
{
  "commandId": "command:blender-create-primitive-remote-smoke-001",
  "rollbackStrategy": "undo_stack",
  "undoCheckpointId": "undo-checkpoint:command:blender-create-primitive-remote-smoke-001",
  "createdObjectId": "Bellona Remote Mutation Cube",
  "sceneInfoObjectId": "object:Bellona Remote Mutation Cube",
  "rollbackAttempted": true,
  "rollbackResult": "succeeded",
  "operator": "MAC-HOST-01 local operator",
  "postRollbackEvidence": {
    "sceneInfoArtifactId": "artifact:<post-rollback-scene-info>",
    "objectAbsent": true
  },
  "limitations": [
    "Undo stack is only valid in the current Blender process.",
    "Later local edits can consume undo steps before the Bellona checkpoint."
  ]
}
```

Do not mark a broad safe-mutation stage closed without either a rollback note
like this or an explicit blocker explaining why rollback could not be verified
on the active hardware/headless Blender run.
