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:
Bellona create primitive: <requested object name or primitive type>
The command result includes checkpoint metadata:
{
"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:
{
"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.
- Locate the command result in the gateway timeline or CLI output.
- Confirm the command result status is
succeeded. - Confirm
output.undoCheckpoint.rollbackStrategyisundo_stack. - Confirm the before/after scene-info evidence identifies exactly one newly created object.
- In Blender, perform one normal undo operation from the active session.
- Capture scene-info again and verify the created object id is no longer present.
- 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:
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:
pnpm nx blender:create-primitive-remote-smoke @bellona/remote-host
The remote CLI should show:
auditEntryTypescontainingcommand.received,command.dispatched, andcommand.completedtimelineResult.resultStatusequal tosucceededmutationResult.undoCheckpointIdpopulatedmutationResult.evidenceReferenceCountgreater 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:
{
"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.