Runbook date: 2026-04-23
Scope: 180.C.17.09
This note records how to verify the Blender production command surface that
Phase 180.C.17 added after the normal CI path has already passed.
Normal CI now proves:
- protocol ownership and schema validation
- host routing and result normalization
- addon mocked-handler coverage
- golden-scene regression coverage for exact before/after scene states
- file snapshot, provenance, transfer-id, and hash-shape expectations
Normal CI does not prove:
- a real Blender binary running on the target rig
- a real Bellona addon session on
localhost:9876 - Blender operator behavior for the installed Blender version and local plugins
- active-session undo behavior inside the live editor UI
- real importer/exporter availability, codec support, or plugin quirks
- viewport/outliner/operator-visible state on the controlled Mac
Do not treat the deterministic CI coverage from 180.C.17.08 as hardware
signoff for real Blender command execution.
Current Automation Baseline#
Committed Blender smoke entrypoints already available in the repo:
pnpm nx blender:scene-info-smoke @bellona/remote-host -- --required
pnpm nx blender:scene-info-remote-smoke @bellona/remote-host -- --require-live-addon
pnpm nx blender:create-primitive-smoke @bellona/remote-host -- --required
pnpm nx blender:create-primitive-remote-smoke @bellona/remote-host -- --live-addon
These cover only:
blender.scene.infoblender.object.create_primitive- the read-only remote route
- the first safe-mutation remote route
The rest of the 180.C.17 surface still needs manual or temporary local
hardware verification through the real Remote Host adapter path on
MAC-HOST-01.
Required Rigs#
Use the rig ids from hardware-rig-inventory.md:
- required:
MAC-HOST-01 - optional for expansion claims only:
WIN-HOST-01,LINUX-RENDER-01
For 180.C.17.09, the minimum accepted evidence comes from MAC-HOST-01 with:
- the repo commit under review
- a supported Blender build from the compatibility matrix
- the Bellona addon enabled and listening on
localhost:9876 - a writable
BELLONA_PROJECT_ROOT
Fixture Project Requirements#
Use one dedicated fixture project root for all 180.C.17 hardware evidence. The
fixture project must contain:
- one
.blendscene with:- one selected mesh object
- one camera
- one light in a separate collection
- one armature/rig object
- one emissive object
- one large static prop
- at least one material with a missing texture reference
- one writable
exports/directory inside the project root - one writable
blender/recovery/directory inside the project root - one
textures/directory with at least one real image texture - one
assets/directory with fixture files for:- GLB/GLTF
- FBX
- OBJ
- USD/USDZ when locally supported
- Alembic
- image texture import
- audio reference import
Use the same fixture scene characteristics across runs so the semantic selector results and import/export counts remain comparable.
Evidence File Location#
Record every 180.C.17.09 hardware run in a Markdown file under:
docs/domains/bellona/extras/remote-control/evidence/180.C.17.09/<date>-MAC-HOST-01-blender-production-commands.md
Each evidence file must include:
- rig id, macOS version, Blender version, addon version, repo commit
- confirmation that the addon remained loopback-only on
localhost:9876 - project-root path used for the run
- exact command envelopes or a faithful excerpt for every command executed
- before/after
blender.scene.infosummaries for every mutating command - result JSON excerpts including evidence ids, artifact ids, undo checkpoints, file snapshots, provenance references, or transfer references
- file hashes and byte sizes for import/export and file-mutation checks
- manual rollback notes for every
undo_stackmutation verified in the live editor - explicit blockers for any command that could not be proven on the active rig
Verification Rules#
- Start every hardware session by proving the local addon and the remote path:
blender:scene-info-smoke -- --requiredblender:scene-info-remote-smoke -- --require-live-addon
- For every mutating command, capture:
- one before
blender.scene.info - the command result
- one after
blender.scene.info
- one before
- For every
undo_stackcommand that is verified in the live editor, perform one explicit Blender undo and record a post-undo scene check. - For every
snapshot_restorefile command, capture the before/after file hash and the active-file path change. - If a command is only proven headlessly, say so explicitly. Headless proof is not the same as live-editor proof.
- If a command falls back to a mocked route or a non-live addon response, the
run does not count for
180.C.17.09.
Command Matrix#
| Command surface | What CI already proves | Headless verification | Live editor verification | Required evidence |
|---|---|---|---|---|
blender.scene.info |
Schema, mocked addon route, golden-scene exactness | Required and already supported by blender:scene-info-smoke |
Recommended through blender:scene-info-remote-smoke -- --require-live-addon |
Local smoke JSON, remote smoke JSON, fallback: false, active scene id, object/material counts |
blender.object.create_primitive |
Protocol, host route, audit/evidence shape, golden scene, rollback note docs | Required and already supported by blender:create-primitive-smoke |
Required once per rig for active-session undo proof through blender:create-primitive-remote-smoke -- --live-addon |
Before/after scene-info, result JSON, undo checkpoint id, post-undo object absence note |
blender.file.open |
Project-root guards, dirty-state guards, file snapshot normalization | Feasible in headless Blender against a fixture .blend |
Recommended for proving behavior when another scene is visibly open in the editor | Before/after active file path, before/after file snapshots, note whether unsaved-change blocking was exercised |
blender.file.save |
Snapshot shape and project-root enforcement | Feasible in headless Blender | Recommended for proving save inside an already edited live session | Before/after hash, modified time, active file path, scene remains loadable after save |
blender.file.save_as |
Snapshot shape and path enforcement | Feasible in headless Blender | Recommended for proving current file retargets to the new path in the live editor | New path inside project root, after-snapshot hash, active file path changed, reopened successfully |
blender.file.pack_resources |
Result normalization and snapshot evidence shape | Feasible in headless Blender when fixture resources exist | Recommended when proving packed-resource status on a live scene with linked textures | Before/after file hash, packed file reopens, external resource note, any size increase |
blender.file.recover_last |
Result normalization and dirty-state denial | Partial headless proof only; acceptable for autosave file path and load result | Required for real unsaved-session recovery behavior because a live editor session is what creates the recovery condition | Recovered path, after snapshot, note whether proof was headless-only or live unsaved-session recovery |
blender.object.delete |
Route, undo checkpoint, scene evidence ids | Feasible headlessly | Required once per rig for live undo confirmation | Object absent after command, object restored after undo, evidence ids |
blender.object.rename |
Route, undo checkpoint, golden-scene exactness | Feasible headlessly | Required once per rig for live undo confirmation | New id/name in scene-info, old id/name restored after undo |
blender.object.duplicate |
Route, undo checkpoint, golden-scene exactness | Feasible headlessly | Required once per rig for live undo confirmation | New duplicate id, selection state, collection membership, duplicate absent after undo |
blender.object.parent |
Route, undo checkpoint, scene evidence shape | Feasible headlessly | Required if the rig or hierarchy is visually inspected in the live editor | Parent-child linkage before/after, hierarchy restored after undo |
blender.object.set_transform |
Route, undo checkpoint, transform result normalization | Feasible headlessly | Recommended when verifying gizmo-visible transform changes in the live viewport | Exact location/rotation/scale before and after, original transform restored after undo |
blender.object.set_visibility |
Route, undo checkpoint, visibility result normalization | Feasible headlessly for data flags | Required if proving actual viewport or outliner visibility behavior, not just data flags | Scene-info visibility flags, optional viewport screenshot, original visibility restored after undo |
blender.collection.hierarchy |
Query normalization and golden-scene exactness | Feasible headlessly | Optional live run only when proving hierarchy against a production scene | Collection ids, parent-child links, object membership |
blender.collection.create |
Route, undo checkpoint, scene evidence shape | Feasible headlessly | Required once per rig for live undo confirmation | New collection id/name, parent link, collection absent after undo |
blender.collection.move_object |
Route, undo checkpoint, golden-scene exactness | Feasible headlessly | Required once per rig for live undo confirmation | Object moved between collections, original membership restored after undo |
blender.collection.set_visibility |
Route, undo checkpoint, result normalization | Feasible headlessly for data flags | Required for real viewport/outliner visibility proof | Collection visibility flag, optional viewport/outliner screenshot, undo note |
blender.collection.set_renderability |
Route, undo checkpoint, result normalization | Feasible headlessly for data flags | Recommended when proving render exclusion in the live editor | Render visibility flag before/after, undo note, renderability screenshot or render setting excerpt if used |
blender.material.create_principled |
Route, undo checkpoint, result normalization | Feasible headlessly | Recommended for real node-tree inspection | Material exists, core parameters set, material absent after undo |
blender.material.assign |
Route, undo checkpoint, golden-scene exactness | Feasible headlessly | Recommended for material slot/UI confirmation | Object slot changed, material assignment visible in scene-info, assignment reverted after undo |
blender.material.set_parameter |
Route, undo checkpoint, result normalization | Feasible headlessly | Recommended for shader preview confirmation | Parameter name/value before/after, original value after undo |
blender.material.bind_texture |
Route, undo checkpoint, result normalization | Feasible headlessly if the texture file is available inside project root | Recommended for actual node-tree and viewport preview proof | Texture path, slot, color-space note, texture binding reverted after undo |
blender.material.semantic_search |
Query normalization only | Feasible headlessly against a fixed fixture scene | Recommended when claiming production-scene semantic fidelity | Query string, ordered matches, stable scores, fixture-scene description |
blender.asset.import scene formats (glb, gltf, fbx, obj, usd, usdz, alembic) |
Allowlist, provenance shape, scene evidence ids, golden-scene exactness for mocked path | Feasible headlessly when the local Blender build supports the format | Recommended for any importer that depends on installed plugins, version quirks, or visible validation | Source hash, imported ids/counts, target collection, undo note, any skipped formats with reason |
blender.asset.import image_texture, audio_reference |
Allowlist, provenance shape, result normalization | Feasible headlessly | Optional live run when previewing the imported asset in the editor matters | Source hash, imported image/sound ids, target data-block ids |
blender.asset.export scene/package formats (glb, gltf, fbx, obj, usd, alembic, blend_package) |
Allowlist, transfer registration shape, host-side hash verification, golden-scene exactness for mocked path | Feasible headlessly for deterministic fixture exports | Recommended when exporter plugins, packaging, or local Blender version differences are in play | Exported file hashes, byte sizes, transfer ids, reopened package where applicable |
blender.asset.export image_sequence |
Result shape and transfer references only | Headless proof is acceptable only when the fixture render path actually writes frames | Recommended on real hardware because render engine, GPU/CPU path, and frame output are environment-dependent | Frame files, per-frame hashes, transfer ids, render engine/device used |
blender.semantic_selector.query presets (all_emissive_objects, selected_character_rig, large_static_props, objects_in_collection, materials_missing_textures) |
Query normalization, deterministic mocked results | Feasible headlessly against a purpose-built fixture scene | Recommended when selectors are claimed against real production content | Selector kind, ordered matches, resolved collection ids, fixture-scene explanation for why each object matched |
Live-Editor Undo Requirement#
All 180.C.17 mutating commands currently declare
rollbackStrategy: "undo_stack" or snapshot_restore.
For undo_stack commands, headless Blender proof is sufficient to show that the
command mutates the real scene and emits an undo checkpoint. It is not
sufficient to prove that the editor undo operator behaves correctly in a live
operator session.
Record at least one live-editor undo note for each mutation family:
- object mutations
- collection mutations
- material mutations
- asset import
- asset export when the exporter mutates local scene state
Use the same rollback-note style already documented in
blender-primitive-rollback-and-undo.md.
Minimum Signoff Bundle For 180.C.17.10#
Before 180.C.17.10 can be checked, the evidence set should contain:
- one headless
scene.infoproof - one live remote
scene.infoproof withfallback: false - one headless primitive mutation proof
- one live remote primitive mutation proof
- one evidence record for every
180.C.17.01through180.C.17.08command family in the matrix above - one explicit blocker note for every format or command variant that could not be proven on the active Blender build
Do not collapse unsupported formats or unverified live-editor behavior into a generic "Blender commands passed" statement. The evidence file must say exactly which commands were proven, on which rig, under which Blender version, and by which verification mode.