Eve library

Blender Primitive Rollback And Undo

Guide

Revision 1

On this page

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.