IU Core MVP — 06 Add/Split/Merge/Delete Structure Ops Contract

Date: 2026-05-21 · Authored in 004_structure_ops_lineage.sql + cutter_agent/iu_core/structure_ops.py.

Substrate

• iu_structure_operation — one governed envelope per operation: operation_type, operation_status, actor_ref, reason, idempotency_key UNIQUE, source_unit_ids uuid[], target_unit_ids uuid[], parent_unit_id, payload jsonb, impact_summary jsonb, created_at, updated_at, enacted_at, created_by.
• iu_relation — typed lineage edges: contains, derived_from, supersedes, replaced_by, merged_from, split_from; carries operation_ref FK to the operation, relation_status, valid_from/to.

Operations

Op	Relations created	Events	Key rules
add_new_piece	contains (if parent)	IU_CHILD_ADDED / IU_ROOT_ADDED	parent optional; SQL links NOT inherited by default
split_large_piece	split_from per output	IU_SPLIT + IU_SQL_LINK_CHANGED	mode children (source stays parent) or replacement_set (source → superseded); link policy copy/move/block/manual_review
merge_small_pieces	merged_from target→each source	IU_MERGED + IU_SQL_LINK_CHANGED	conflict policy block/prefer_target/manual_review; link collisions fail closed
deprecate_piece (= governed delete)	none new	IU_DEPRECATED	NO hard delete; children require explicit dependency_action; active links block unless disabled/retired
replace_piece	supersedes new→old, replaced_by old→new	IU_REPLACED + IU_SQL_LINK_CHANGED	old → superseded/deprecated after review
reparent_piece	contains rewrite	IU_REPARENTED	cycle-checked (see report 05)

delete_piece is modeled as deprecate_piece — physical delete is not a default operation and requires a separate GPT/User rule + exceptional evidence. supersede / replaced_by are realized as iu_relation types, not new ops.

Governance / idempotency / audit

• Governance: every op starts draft; enactment routes through cutter_governance.cut_change_set + cut_change_set_affected_row. A draft op cannot self-advance to production enactment.
• Idempotency: idempotency_key UNIQUE on iu_structure_operation; structure_operation_key() is order-invariant over source/target unit ids (re-running the same logical op deduplicates).
• Status machine (structure_ops.py, CHECK in SQL): draft→{planned,cancelled}, planned→{enacted,cancelled,failed}, enacted→{rolled_back}, failed→{planned,cancelled}; cancelled & rolled_back terminal. CHECK enacted ⇔ enacted_at IS NOT NULL.
• Audit: created_at/updated_at/enacted_at, actor_ref, created_by, reason, payload, impact_summary on every op; relations carry created_by, valid_from, operation_ref.

Lineage / provenance

Lineage keys carried across op payloads, relation rows, version profiles: split_from, merged_from, derived_from, supersedes, replaced_by, source_span, source_reference, operation_ref. iu_lifecycle_log.metadata should record operation_ref when a lifecycle transition is caused by a structure op.

Failure modes / rollback / partial states

• Cycle risk, ambiguous merge/split, duplicate canonical claim, SQL-link collision ⇒ fail closed before event emission; op → failed.
• Compensation: an enacted op moves to rolled_back via an inverse op; relations retire via relation_status + valid_to (never DELETE).
• Partial rollback: per-relation relation_status allows retiring a subset of an operation's edges without dropping the operation row.
• Enacted source content is immutable — split/merge/replace create new units/versions, never rewrite enacted content.

Helper implemented + tested

structure_ops.py — OPERATION_TYPES / RELATION_TYPES / OBJECT_KINDS / status-transition table / IU_EVENT_VOCABULARY / STRUCTURE_OP_EVENTS / DEPENDENCY_POLICY. 7 contract tests in test_iu_core_ddl.py assert the Python enums match the SQL CHECK constraints and the status machine rejects illegal transitions.