# Blender Production Command Hardware And Headless Verification

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`](./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`](./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.
