Operator Runbook — 25000x addendum

File template versioning (recipe)

Pre-req: pieces of the target v1 collection exist; v1 collection has been fn_iu_collection_mark_as_template'd (mig 031); composer gate is closed.

BEGIN;
UPDATE dot_config SET value='true' WHERE key='iu_core.composer_enabled';

SELECT fn_iu_compose(
    'tpl:<family>/v2',
    '<kind>',
    '<title>',
    '<description>',
    jsonb_build_array(
        jsonb_build_object('role','title','iu_id','<full uuid>'),
        jsonb_build_object('role','intro','new_piece',
            jsonb_build_object(
                'canonical_address','iu_core/template/<macro>/<family>-v2/<piece-name>',
                'title','...', 'body','...',
                'unit_kind','design_doc_section',
                'section_type','section')),
        -- ... remaining reused pieces by iu_id
    ),
    '<actor>'
);

UPDATE dot_config SET value='false' WHERE key='iu_core.composer_enabled';

SELECT fn_iu_collection_mark_as_template(
    (SELECT id FROM iu_piece_collection WHERE collection_key='tpl:<family>/v2'),
    '<label>', '<note>', '<actor>');

SELECT fn_iu_collection_register_template_version(
    '<v1_coll_id>'::uuid, 'tpl:<family>', 'v1', 1, NULL, '<actor>');

SELECT fn_iu_collection_register_template_version(
    (SELECT id FROM iu_piece_collection WHERE collection_key='tpl:<family>/v2'),
    'tpl:<family>', 'v2', 2, '<v1_coll_id>'::uuid, '<actor>');

COMMIT;

Event → instance auto-instantiate (dry_run recipe)

BEGIN;
UPDATE dot_config SET value='true' WHERE key='iu_core.composer_enabled';

SELECT fn_iu_auto_instantiate_from_event(
    '<event_uuid>'::uuid,
    'template.published',
    '<template_coll_id>'::uuid,
    '<unique_suffix>',
    'dry_run',
    '<actor>',
    '<optional note>');

UPDATE dot_config SET value='false' WHERE key='iu_core.composer_enabled';
ROLLBACK;  -- or COMMIT to keep the dry_run-tagged instance durable

Returns one of: ok / idempotent_replay / composer_gate_closed / template_collection_not_found / template_not_marked / template_has_no_active_pieces / instance_collection_key_collision / invalid_input / invalid_emit_mode.

Event → instance auto-instantiate (live recipe)

BEGIN;
UPDATE dot_config SET value='true' WHERE key='iu_core.composer_enabled';
UPDATE dot_config SET value='true' WHERE key='iu_core.auto_instantiate_enabled';

SELECT fn_iu_auto_instantiate_from_event(
    '<event_uuid>'::uuid, '<event_type>', '<template_coll_id>'::uuid,
    '<unique_suffix>', 'live', '<actor>', '<note>');

UPDATE dot_config SET value='false' WHERE key='iu_core.composer_enabled';
UPDATE dot_config SET value='false' WHERE key='iu_core.auto_instantiate_enabled';
COMMIT;

Refuses with live_gate_closed if iu_core.auto_instantiate_enabled=false.

Bulk scaleout via the orchestrator

BEGIN;
UPDATE dot_config SET value='true' WHERE key='iu_core.composer_enabled';
UPDATE dot_config SET value='true' WHERE key='iu_core.auto_instantiate_enabled';

DO $$
DECLARE i int; v_result jsonb;
BEGIN
    FOR i IN 1..N LOOP
        v_result := fn_iu_auto_instantiate_from_event(
            ('25000bxx-0000-4000-8000-' || lpad(i::text, 12, '0'))::uuid,
            'template.published',
            (SELECT id FROM iu_piece_collection WHERE collection_key='<template_key>'),
            '<batch-tag>-' || lpad(i::text, 3, '0'),
            'live', '<actor>');
        RAISE NOTICE 'bulk #% -> %', i, v_result->>'status';
    END LOOP;
END;
$$;

UPDATE dot_config SET value='false' WHERE key='iu_core.composer_enabled';
UPDATE dot_config SET value='false' WHERE key='iu_core.auto_instantiate_enabled';
COMMIT;

UUID prefix must be hex-valid (e.g. 25000b00- works; 25000bk0- does not).

Rollback recipes

-- Per-actor dry-run (recommended first)
SELECT fn_iu_auto_instantiate_rollback_by_actor('<actor>', true);

-- Per-actor durable
BEGIN;
SELECT fn_iu_auto_instantiate_rollback_by_actor('<actor>', false);
COMMIT;

-- Per-substrate (drop mig 033)
-- psql -c "SET iu_core.force_rollback_033=true;" \
--      -f sql/iu-core/rollback/033_auto_instantiate_from_event.rollback.sql

Observability cheatsheet

SELECT * FROM v_iu_template_observability ORDER BY collection_key;
SELECT * FROM v_iu_template_version_chain ORDER BY template_family, version_seq;
SELECT * FROM v_iu_auto_instantiate_event_log ORDER BY created_at DESC LIMIT 50;
SELECT * FROM v_iu_auto_instantiate_event_summary;
SELECT triggered_by, count(*), array_agg(instance_collection_id)
  FROM iu_auto_instantiate_event_log GROUP BY triggered_by;

Safety reminders

• Never enable iu_core.delivery_enabled without explicit authority.
• Never enable iu_core.retention_enabled without a candidates audit.
• Never touch Qdrant production_documents from the orchestrator.
• Always close all gates before COMMIT.
• iu_core.auto_instantiate_enabled must default false between operator sessions.
• PR #669 / Nuxt deploy / external delivery routes — OUT-OF-SCOPE.