Eve library

Blender Production Command Hardware And Headless Verification

Guide

Revision 1

On this page

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:

bash
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.info
  • blender.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 .blend scene 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:

text
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.info summaries 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_stack mutation verified in the live editor
  • explicit blockers for any command that could not be proven on the active rig

Verification Rules#

  1. Start every hardware session by proving the local addon and the remote path:
    • blender:scene-info-smoke -- --required
    • blender:scene-info-remote-smoke -- --require-live-addon
  2. For every mutating command, capture:
    • one before blender.scene.info
    • the command result
    • one after blender.scene.info
  3. For every undo_stack command that is verified in the live editor, perform one explicit Blender undo and record a post-undo scene check.
  4. For every snapshot_restore file command, capture the before/after file hash and the active-file path change.
  5. If a command is only proven headlessly, say so explicitly. Headless proof is not the same as live-editor proof.
  6. 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.info proof
  • one live remote scene.info proof with fallback: false
  • one headless primitive mutation proof
  • one live remote primitive mutation proof
  • one evidence record for every 180.C.17.01 through 180.C.17.08 command 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.