40000x · 02 — Migration 034: Auto-instantiate orchestrator DOT registration

Goal

Promote the two productized orchestrator functions shipped by migration 033 (25000x) from "callable function" to "governed DOT command":

• fn_iu_auto_instantiate_from_event(uuid,text,uuid,text,text,text,text) → jsonb
• fn_iu_auto_instantiate_rollback_by_actor(text,boolean) → jsonb

What 034 adds

Data-only catalog seed — no new tables / views / fns / triggers / configs / event_types / routes. D9 surface stays at 181 objects.

Two INSERT INTO public.dot_iu_command_catalog rows:

command_name	category	mutating	reversible	target_functions
dot_iu_auto_instantiate_from_event	collection	t	t	{fn_iu_auto_instantiate_from_event}
dot_iu_auto_instantiate_rollback_by_actor	lifecycle	t	t	{fn_iu_auto_instantiate_rollback_by_actor}

Both ON CONFLICT (command_name) DO NOTHING — idempotent.

Preflight (in the migration itself)

A DO $preflight$ block fails loudly if either underlying fn from migration 033 is missing:

IF NOT v_have_from_event OR NOT v_have_rollback THEN
    RAISE EXCEPTION '034 preflight: migration 033 substrate missing …
                     — apply 033 first';
END IF;

Live apply transcript (verbatim, irrelevant lines elided)

$ docker exec postgres psql -U directus -d directus -v ON_ERROR_STOP=on \
    -f /tmp/034_auto_instantiate_dot_registration.sql
BEGIN
DO
INSERT 0 2
-- 034 verification: catalog size + every target_function resolvable
    check    | catalog_rows | expected_26
-------------+--------------+-------------
 034_catalog |           26 | t

    check    | distinct_target_functions | all_resolvable
-------------+---------------------------+----------------
 034_targets |                        24 | t

    check     |                                  rows_present
--------------+--------------------------------------------------------------------------------
 034_new_rows | {dot_iu_auto_instantiate_from_event,dot_iu_auto_instantiate_rollback_by_actor}

COMMIT

Then the R280 seed (updated in this commit) was re-applied as a no-op verification of SSOT consistency: INSERT 0 0 confirms the SSOT-side seed matches the live catalog row-for-row.

Rollback proof (BEGIN/COMMIT cycle on live)

The rollback file removes the two rows under a REFUSED guard on dot_iu_command_run rows. A small schema mismatch was caught during the live rollback proof: the guard initially referenced dot_iu_command_run.command but the column is command_name. Patched, re-shipped, re-run — final guarded delete succeeded; catalog returned 26 → 24 → 26 cleanly.

Pinning updates in the same commit

Site	Before	After
sql/iu-core/runtime/280_operator_runtime_catalog_seed.sql	24 rows + expected_24	26 rows + expected_26
cutter_agent/iu_core/dot_commands.py module docstring	"32 dot_iu_* commands"	"34 dot_iu_* commands"
cutter_agent/iu_core/dot_commands.py _REGISTRY	32 entries	34 entries (2 new builders + 2 _cmd(...))
tests/test_iu_core_500x_operator_surface.py::test_twenty_governed_commands	assertEqual(len(governed), 24)	assertEqual(len(governed), 26)
tests/test_iu_core_540x_operator_runtime.py::test_seed_row_count_matches_governed_registry	len(governed), 24 + "= 24"	len(governed), 26 + "= 26"

test_iu_core_ddl.py::EXPECTED_COUNTS was not bumped — migration 034 is data-only, so D9 (table=29, view=30, function=65, trigger=6, config=13, event_type=22, route=16, total 181) is unchanged.

Operator usage examples (post-040000x)

python -m cutter_agent.iu_core.dot_commands explain \
    dot_iu_auto_instantiate_from_event \
    event_id=<uuid> event_type=template.instance_auto_composed \
    template_collection_id=<uuid> instance_key_suffix=demo-001 \
    emit_mode=dry_run actor=operator note='trial run'

python -m cutter_agent.iu_core.dot_commands explain \
    dot_iu_auto_instantiate_rollback_by_actor \
    actor=operator dry_run=true

Gate semantics — unchanged

The new DOT commands do not introduce or alter any gate. The orchestrator's existing two-gate semantics from migration 033 continue to govern:

• dry-run mode: requires iu_core.composer_enabled=true (currently false).
• live mode: requires both composer_enabled=true AND auto_instantiate_enabled=true (both currently false).