05 — External operator commands (new in 3000x)

1. Scope

cutter_agent/iu_core/dot_commands.py previously catalogued 17 OperatorRuntime-governed dot_iu_* commands across five categories (collection / piece / lifecycle / read / health). 3000x adds a sixth category external with 7 read-only commands that target the three external surfaces (Directus collection, Qdrant collection, the new three-axis cache). They are deliberately NOT routed through OperatorRuntime because their plans target views/tables directly.

2. The seven new commands

Command	Category	Mutating	Targets
dot_iu_three_axis_envelope_refresh	external	yes	fn_iu_three_axis_envelope_refresh_if_stale
dot_iu_three_axis_envelope_drift_check	external	no	fn_iu_three_axis_envelope_drift_check
dot_iu_three_axis_envelope_status	external	no	v_iu_three_axis_envelope_refresh_status
dot_iu_directus_verify	external	no	iu_three_axis_envelope, directus_permissions
dot_iu_nuxt_config_verify	external	no	(NOTICE-only — emits expected env name)
dot_iu_qdrant_collection_status	external	no	v_iu_qdrant_collection_active, iu_vector_sync_point
dot_iu_external_healthcheck	external	no	aggregates the above three surfaces in one call

All 7 commands are reversible (reversible=true), but only one is mutating — the refresh wrapper.

3. Example plans

$ python3 -m cutter_agent.iu_core.dot_commands explain \
      dot_iu_three_axis_envelope_refresh actor=ops dry_run=true
-- dot_iu_three_axis_envelope_refresh: Drift-gated refresh of
   iu_three_axis_envelope from v_ui_iu_three_axis_envelope. Audited.
-- reversal: runtime/rollback/330: DELETE log rows by actor; truncate
   iu_three_axis_envelope rebuilds from the view.
SELECT * FROM public.fn_iu_three_axis_envelope_refresh_if_stale(
    'ops', true, false);

$ python3 -m cutter_agent.iu_core.dot_commands explain \
      dot_iu_external_healthcheck
SELECT 'three_axis_cache' AS surface,
       jsonb_build_object('in_sync', ..., 'view_count', ...,
                          'table_count', ...) AS detail
  FROM (SELECT public.fn_iu_three_axis_envelope_drift_check() AS d) s;
SELECT 'directus_collection' AS surface,
       jsonb_build_object('permission_rows',
                          (SELECT count(*) FROM directus_permissions
                            WHERE collection='iu_three_axis_envelope'
                              AND action='read'),
                          'table_rows', ...) AS detail;
SELECT 'qdrant_collection' AS surface,
       jsonb_build_object('active', ..., 'sync_points_indexed', ...)
                          AS detail;

4. Why bypass OperatorRuntime

OperatorRuntime's _assert_governed requires every plan statement to contain public.fn_ — the contract is "every mutation goes through a governed plpgsql function". External commands target read-only views (v_iu_qdrant_collection_active, v_iu_three_axis_envelope_refresh_status) and tables (directus_permissions, iu_three_axis_envelope) where that constraint does not apply. They are designed for direct psql or SDK execution.

Test impact (3000x):

• tests/test_iu_core_500x_operator_surface.py::test_seventeen_governed_commands asserts len(governed)==17 and len(external)==7.
• tests/test_iu_core_540x_operator_runtime.py::test_seed_* filters external commands out of the runtime/280 catalog seed expectations.
• tests/test_iu_core_540x_operator_runtime.py::test_governed_plan_passes_safety_check skips external commands when asserting _assert_governed holds.

5. DOT visibility

All targets the external commands name are registered in runtime/110_iu_core_dot_conformance_scan.sql:

• iu_three_axis_envelope, iu_three_axis_envelope_refresh_log (tables);
• v_iu_qdrant_collection_active, v_iu_three_axis_envelope_refresh_status (views);
• fn_iu_three_axis_envelope_refresh_if_stale, fn_iu_three_axis_envelope_drift_check, fn_iu_three_axis_envelope_refresh (functions);
• iu_core.three_axis_auto_refresh_enabled (config);
• iu_vector_sync_point, iu_qdrant_collection_registry (tables; carried forward).

The only non-IU-Core target is directus_permissions (Directus core table) — explicitly skipped in test_every_command_target_is_dot_visible.

6. No hardcoded literals

• The collection name in every external command defaults from the optional collection param (caller can override). The default 'iu_three_axis_envelope' mirrors directus_registration.DIRECTUS_THREE_AXIS_COLLECTION — single definition point.
• The Nuxt env name IU_CORE_DIRECTUS_COLLECTION lives in nuxt_assembly_contract.py recommendation text only; the verify command emits it via RAISE NOTICE, no Nuxt source literal added.
• The Qdrant collection name is read from the registry view (v_iu_qdrant_collection_active), never typed.