# TASK-159-03-01: Addon Scene Context, Lifecycle, Inspection, And Topology Split

**Parent:** [TASK-159-03](./TASK-159-03_Addon_Scene_Handler_Modularization_And_Blender_Ownership_Boundaries.md)
**Status:** ✅ Done
**Priority:** 🔴 High

## Objective

Split the addon lifecycle/context, structural-read, and inspection/topology
branch into focused leaves so the Blender owner path stays execution-ready
under the leaf-size rule.

This subtask still owns the same truth-read surface plus the early
object-lifecycle helpers that currently sit next to it in `SceneHandler`.
Creation, visibility, and custom-property utilities move under
[TASK-159-03-04](./TASK-159-03-04_Addon_Scene_Creation_Visibility_And_Metadata_Utilities.md).

## Repository Touchpoints

- `blender_addon/application/handlers/scene.py`
- likely new helper modules such as:
  - `blender_addon/application/handlers/scene_lifecycle_context_mixin.py`
  - `blender_addon/application/handlers/scene_structural_read_mixin.py`
  - `blender_addon/application/handlers/scene_inspection_mixin.py`
- `tests/unit/tools/scene/test_scene_mode.py`
- `tests/unit/tools/scene/test_scene_get_mode_handler.py`
- `tests/unit/tools/scene/test_scene_tools.py`
- `tests/unit/tools/scene/test_scene_tools_extended.py`
- `tests/unit/tools/scene/test_scene_mcp_tools_batch.py`
- `tests/unit/tools/scene/test_scene_inspect_modifiers.py`
- `tests/unit/tools/scene/test_get_constraints.py`
- `tests/unit/tools/scene/test_scene_inspect_mesh_topology.py`
- `tests/unit/tools/scene/test_snapshot_state_visibility.py`
- `tests/unit/tools/test_handler_rpc_alignment.py`
- `tests/e2e/tools/scene/test_scene_inspect_material_slots.py`
- `tests/e2e/tools/scene/test_scene_clean_scene.py`
- `tests/e2e/tools/scene/test_snapshot_tools.py`

## Current Code Anchors

- `SceneHandler.list_objects(...)`
- `SceneHandler.delete_object(...)`
- `SceneHandler.clean_scene(...)`
- `SceneHandler.duplicate_object(...)`
- `SceneHandler.set_active_object(...)`
- `SceneHandler.get_mode(...)`
- `SceneHandler.list_selection(...)`
- `SceneHandler.inspect_object(...)`
- `SceneHandler.inspect_material_slots(...)`
- `SceneHandler.inspect_modifiers(...)`
- `SceneHandler.get_constraints(...)`
- `SceneHandler.snapshot_state(...)`
- `SceneHandler.get_hierarchy(...)`
- `SceneHandler.get_bounding_box(...)`
- `SceneHandler.get_origin_info(...)`
- `SceneHandler.inspect_mesh_topology(...)`

## Pseudocode

```python
lifecycle_context_leaf = [
    "list_objects",
    "delete_object",
    "clean_scene",
    "duplicate_object",
    "set_active_object",
    "get_mode",
    "list_selection",
]
structural_read_leaf = [
    "snapshot_state",
    "get_hierarchy",
    "get_bounding_box",
    "get_origin_info",
]
inspection_topology_leaf = [
    "inspect_object",
    "inspect_material_slots",
    "inspect_modifiers",
    "get_constraints",
    "inspect_mesh_topology",
]

for rpc_method in lifecycle_context_leaf:
    keep_public_scene_handler_name(rpc_method)
    move_implementation_to_lifecycle_context_mixin(rpc_method)

for rpc_method in structural_read_leaf:
    keep_public_scene_handler_name(rpc_method)
    move_implementation_to_structural_read_mixin(rpc_method)

for rpc_method in inspection_topology_leaf:
    keep_public_scene_handler_name(rpc_method)
    move_implementation_to_inspection_mixin(rpc_method)

preserve_main_thread_safety()
preserve_existing_rpc_payloads()
```

## Implementation Notes

- Keep lifecycle/context helpers separate from structural-read helpers even if
  they land in adjacent addon mixins; they have different validation and RPC
  coupling.
- Keep the inspection action matrix plus topology together only where the same
  Blender-owned truth helpers already share mesh/material/constraint state.
- Leave creation/visibility/custom-property utilities on `TASK-159-03-04` and
  world/render/color-management on `TASK-159-03-05`; do not let this branch
  absorb those responsibilities again.
- Preserve Blender main-thread and evaluated-mesh safety patterns across every
  child leaf.

## Execution Structure

| Order | Leaf | Purpose |
|------|------|---------|
| 1 | [TASK-159-03-01-01](./TASK-159-03-01-01_Addon_Scene_Lifecycle_And_Context_Read_Split.md) | Separate early object lifecycle helpers plus mode/selection/context reads into one focused addon leaf |
| 2 | [TASK-159-03-01-02](./TASK-159-03-01-02_Addon_Scene_Snapshot_And_Structural_Read_Split.md) | Separate snapshot, hierarchy, bbox, and origin helpers into one structural-read addon leaf |
| 3 | [TASK-159-03-01-03](./TASK-159-03-01-03_Addon_Scene_Inspection_Action_Matrix_And_Topology_Split.md) | Separate the inspection action matrix plus topology helpers into one focused truth-read addon leaf |

## Runtime / Security Contract Notes

- keep Blender state reads and object-lifecycle truth helpers on the
  main-thread-safe addon path
- preserve current topology payload shapes plus snapshot/hierarchy/bbox/origin
  conventions
- preserve current list/clean/duplicate/set-active/get-mode/list-selection
  semantics and result envelopes
- do not move truth reads into server-side services during this leaf

## Tests To Add/Update

- `tests/unit/tools/scene/test_scene_mode.py`
- `tests/unit/tools/scene/test_scene_get_mode_handler.py`
- `tests/unit/tools/scene/test_scene_tools.py`
- `tests/unit/tools/scene/test_scene_tools_extended.py`
- `tests/unit/tools/scene/test_scene_mcp_tools_batch.py`
- `tests/unit/tools/scene/test_scene_inspect_modifiers.py`
- `tests/unit/tools/scene/test_get_constraints.py`
- `tests/unit/tools/scene/test_scene_inspect_mesh_topology.py`
- `tests/unit/tools/test_handler_rpc_alignment.py`
- `tests/e2e/tools/scene/test_scene_inspect_material_slots.py`
- `tests/e2e/tools/scene/test_scene_clean_scene.py`
- `tests/e2e/tools/scene/test_snapshot_tools.py`

## Validation Commands

- `PYTHONPATH=. poetry run pytest tests/unit/tools/scene/test_scene_mode.py tests/unit/tools/scene/test_scene_get_mode_handler.py tests/unit/tools/scene/test_scene_tools.py tests/unit/tools/scene/test_scene_tools_extended.py tests/unit/tools/scene/test_scene_mcp_tools_batch.py tests/unit/tools/scene/test_scene_inspect_modifiers.py tests/unit/tools/scene/test_get_constraints.py tests/unit/tools/scene/test_scene_inspect_mesh_topology.py tests/unit/tools/scene/test_snapshot_state_visibility.py tests/unit/tools/test_handler_rpc_alignment.py tests/e2e/tools/scene/test_scene_inspect_material_slots.py tests/e2e/tools/scene/test_scene_clean_scene.py tests/e2e/tools/scene/test_snapshot_tools.py -q`

## Docs To Update

- inherit parent docs closeout unless addon inspection ownership wording changes

## Changelog Impact

- include in the parent `TASK-159` changelog entry when shipped

## Acceptance Criteria

- this branch is decomposed into focused lifecycle/context, structural-read,
  and inspection/topology leaves instead of one oversized truth-read pass
- Blender truth-read payloads stay unchanged for list/clean/duplicate/mode,
  inspect, material-slot, modifier, constraint, snapshot, hierarchy,
  bbox/origin, and topology paths across the child leaves
- RPC alignment tests still pass for the extracted lifecycle/context,
  structural-read, and inspection methods

## Status / Board Update

- keep promoted tracking on parent `TASK-159`
- execute this branch through the focused leaves below instead of landing all
  truth-read work in one oversized pass

## Completion Summary

Completed on 2026-05-04.

- closed the full addon truth-read branch by landing:
  - `TASK-159-03-01-01` lifecycle/context mixin split
  - `TASK-159-03-01-02` structural-read mixin split
  - `TASK-159-03-01-03` inspection/topology mixin split
- `blender_addon/application/handlers/scene.py` now delegates those concerns to
  focused mixins instead of keeping one mixed truth-read block inline
- preserved addon RPC method names, payloads, and Blender main-thread truth
  behavior across lifecycle, structural-read, inspection, constraint, and
  topology surfaces
