IU Core Worker Live — 04 Structure-ops workflow package

What it is

cutter_agent/iu_core/structure_ops_workflow.py — the repo-backed executable driver for the plan → apply → verify → rollback envelope specified in the event-worker macro KB doc 06. It moves structure-ops from a design package to running, unit-tested code.

Surface

• StructureOpRequest — operation_type, source_unit_ids, new_unit_ids, new_parent_id, payload, actor; .operation_key is the deterministic structure_operation_key (order-invariant on unit ids).
• ImpactSummary — affected units, tree paths to refresh, events to emit (events_for_operation).
• StructureOpPlan / StructureOpOutcome — phase results.
• StructureStore Protocol — the substrate seam (get_adjacency, unit_exists, record_operation, set_operation_status, set_parent, write_relation, retire_relation, refresh_tree_paths, …).
• InMemoryStructureStore — a fully executable in-memory store; the workflow is unit-testable end-to-end against it.
• StructureOpsWorkflow — plan / apply / verify / rollback.

The four phases

1. plan (dry-run) — validate (op type, source units exist, reparent tree safety via tree.assert_acyclic_reparent), compute ImpactSummary, record the envelope draft→planned. Idempotent: re-planning the same key returns the existing plan (replayed=True). Mutates no tree.
2. apply — planned→enacted; mutate adjacency / lineage edges / tree-path refresh through the store. Idempotent (re-apply of enacted is a no-op). reparent_piece is fully executable; add/split/merge/replace write the lineage edges (contains / split_from / merged_from / replaced_by); deprecate_piece is a lifecycle-status change only.
3. verify — read-only: re-derive the adjacency, assert the tree is acyclic.
4. rollback — enacted→rolled_back; reverse the adjacency change from a pre-apply snapshot, retire the contains edges. KB doc 06 H4: enacted_at is retained through rollback.

Executable vs skeleton

plan/apply/verify/rollback are executable against InMemoryStructureStore — the whole workflow runs and is tested. The skeleton is the live PostgreSQL-backed StructureStore: implementing its methods (birth gate for IU creation, fn_iu_tree_assert_acyclic, iu_tree_path refresh) is the next structure-ops macro's work. Reuses structure_ops.py (vocabulary), tree.py (cycle logic), idempotency.py (keys).

Tests: TestStructureOpsWorkflow (7) — reparent full cycle, plan idempotency, apply guard, descendant-reparent blocked at plan, impact events match contract, lineage relations written, operation key deterministic.