@lobu/cli 6.0.0 → 6.1.1

package/dist/db/migrations/20260425100000_normalize_watcher_feedback.sql

@@ -0,0 +1,91 @@
+-- migrate:up
+
+-- Normalize watcher feedback to one row per corrected field.
+--
+-- The original `watcher_window_feedback` stored every correction batch as a
+-- single JSONB blob (`corrections`) with one shared `notes` column. That
+-- shape blocks per-field notes, makes "latest correction per field" a JSONB
+-- aggregation, and lets duplicate submissions for the same field accumulate
+-- forever (the prompt summary then injects every historical version).
+--
+-- New table is per-field with explicit mutation kind so structural edits
+-- (remove an array item, append a new one) live alongside value corrections
+-- without overloading the value column. Existing rows are migrated by
+-- expanding the JSONB map into one row per key.
+
+CREATE TABLE IF NOT EXISTS public.watcher_window_field_feedback (
+    id bigserial PRIMARY KEY,
+    window_id integer NOT NULL REFERENCES public.watcher_windows(id) ON DELETE CASCADE,
+    watcher_id integer NOT NULL REFERENCES public.watchers(id) ON DELETE CASCADE,
+    organization_id text NOT NULL,
+    field_path text NOT NULL,
+    mutation text NOT NULL DEFAULT 'set'
+        CHECK (mutation IN ('set', 'remove', 'add')),
+    corrected_value jsonb,
+    note text,
+    created_by text NOT NULL,
+    created_at timestamp with time zone NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_wwff_watcher_field_recent
+    ON public.watcher_window_field_feedback (watcher_id, field_path, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_wwff_window
+    ON public.watcher_window_field_feedback (window_id);
+
+INSERT INTO public.watcher_window_field_feedback (
+    window_id, watcher_id, organization_id,
+    field_path, mutation, corrected_value, note,
+    created_by, created_at
+)
+SELECT
+    f.window_id,
+    f.watcher_id,
+    f.organization_id,
+    kv.key AS field_path,
+    'set' AS mutation,
+    kv.value AS corrected_value,
+    f.notes AS note,
+    f.created_by,
+    f.created_at
+FROM public.watcher_window_feedback f,
+     LATERAL jsonb_each(f.corrections) AS kv;
+
+DROP TABLE IF EXISTS public.watcher_window_feedback;
+
+-- migrate:down
+
+CREATE TABLE IF NOT EXISTS public.watcher_window_feedback (
+    id bigserial PRIMARY KEY,
+    window_id integer NOT NULL REFERENCES public.watcher_windows(id) ON DELETE CASCADE,
+    watcher_id integer NOT NULL REFERENCES public.watchers(id) ON DELETE CASCADE,
+    organization_id text NOT NULL,
+    corrections jsonb NOT NULL,
+    notes text,
+    created_by text NOT NULL,
+    created_at timestamp with time zone NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_wwf_window ON public.watcher_window_feedback(window_id);
+CREATE INDEX IF NOT EXISTS idx_wwf_watcher ON public.watcher_window_feedback(watcher_id);
+
+-- Best-effort rollback: structural mutations ('add' / 'remove') don't fit
+-- the old shape and are dropped (WHERE mutation = 'set'). When multiple
+-- contributors edited the same window, MAX(note) and MAX(created_by) pick
+-- one arbitrarily — this is an emergency recovery path, not a clean inverse.
+INSERT INTO public.watcher_window_feedback (
+    window_id, watcher_id, organization_id,
+    corrections, notes, created_by, created_at
+)
+SELECT
+    window_id,
+    watcher_id,
+    organization_id,
+    jsonb_object_agg(field_path, COALESCE(corrected_value, 'null'::jsonb)) AS corrections,
+    MAX(note) AS notes,
+    MAX(created_by) AS created_by,
+    MAX(created_at) AS created_at
+FROM public.watcher_window_field_feedback
+WHERE mutation = 'set'
+GROUP BY window_id, watcher_id, organization_id;
+
+DROP TABLE IF EXISTS public.watcher_window_field_feedback;

package/dist/db/migrations/20260425120000_add_run_diagnostics.sql

@@ -0,0 +1,20 @@
+-- migrate:up
+
+-- Add diagnostic columns to runs so subprocess failures carry enough context
+-- to diagnose without reading gateway pod logs.
+--
+-- output_tail: redacted tail (~16 KiB) of child stdout+stderr at exit.
+-- exit_code:   subprocess exit code, NULL when terminated by IPC error path.
+-- exit_signal: signal name (e.g. SIGKILL) when killed.
+-- exit_reason: categorized — ok | error_message | timeout | oom | crash.
+ALTER TABLE public.runs ADD COLUMN output_tail TEXT NULL;
+ALTER TABLE public.runs ADD COLUMN exit_code INTEGER NULL;
+ALTER TABLE public.runs ADD COLUMN exit_signal TEXT NULL;
+ALTER TABLE public.runs ADD COLUMN exit_reason TEXT NULL;
+
+-- migrate:down
+
+ALTER TABLE public.runs DROP COLUMN IF EXISTS exit_reason;
+ALTER TABLE public.runs DROP COLUMN IF EXISTS exit_signal;
+ALTER TABLE public.runs DROP COLUMN IF EXISTS exit_code;
+ALTER TABLE public.runs DROP COLUMN IF EXISTS output_tail;

package/dist/db/migrations/20260425130000_add_repair_agent_plumbing.sql

@@ -0,0 +1,46 @@
+-- migrate:up
+
+-- Repair-agent plumbing for connector reliability.
+--
+-- When a feed accumulates persistent failures, the worker-completion path
+-- can open a Lobu agent thread for triage. These columns track the
+-- per-feed override, the open thread (if any), the lifetime budget of
+-- repair attempts, the start of the current failure streak, and the
+-- last-posted content hash for append throttling.
+ALTER TABLE public.feeds
+  ADD COLUMN repair_agent_id text NULL,
+  ADD COLUMN repair_thread_id text NULL,
+  ADD COLUMN repair_attempt_count integer NOT NULL DEFAULT 0,
+  ADD COLUMN last_repair_at timestamp with time zone NULL,
+  ADD COLUMN first_failure_at timestamp with time zone NULL,
+  ADD COLUMN last_repair_post_hash text NULL;
+
+-- The unique partial index documents intent: a feed has at most one open
+-- repair thread at a time. (`feeds.id` is already PK so the constraint is
+-- redundant for uniqueness; the actual race guard is the conditional
+-- UPDATE on repair_thread_id IS NULL in the worker-completion path.)
+CREATE UNIQUE INDEX feeds_open_repair_thread_uniq
+  ON public.feeds (id) WHERE repair_thread_id IS NOT NULL;
+
+-- Per-connector default repair agent. When a feed has no explicit
+-- repair_agent_id, the trigger logic falls back to this value.
+ALTER TABLE public.connector_definitions
+  ADD COLUMN default_repair_agent_id text NULL;
+
+-- Per-org kill switch. When FALSE, no repair threads are opened for any
+-- feed in the org regardless of per-feed configuration.
+ALTER TABLE public.organization
+  ADD COLUMN repair_agents_enabled boolean NOT NULL DEFAULT TRUE;
+
+-- migrate:down
+
+ALTER TABLE public.organization DROP COLUMN IF EXISTS repair_agents_enabled;
+ALTER TABLE public.connector_definitions DROP COLUMN IF EXISTS default_repair_agent_id;
+DROP INDEX IF EXISTS feeds_open_repair_thread_uniq;
+ALTER TABLE public.feeds
+  DROP COLUMN IF EXISTS last_repair_post_hash,
+  DROP COLUMN IF EXISTS first_failure_at,
+  DROP COLUMN IF EXISTS last_repair_at,
+  DROP COLUMN IF EXISTS repair_attempt_count,
+  DROP COLUMN IF EXISTS repair_thread_id,
+  DROP COLUMN IF EXISTS repair_agent_id;

package/dist/db/migrations/20260426120000_entities_entity_type_fk.sql

@@ -0,0 +1,101 @@
+-- migrate:up
+
+-- Convert entities.entity_type from a text slug to an FK on entity_types(id).
+-- Two motivations folded into one change:
+--
+--   1. Integrity. Today entity_types renames orphan all referencing entities
+--      (slug-based reference is silent FK with no enforcement). Hard-deletes
+--      bypass the validator entirely. With a real FK, Postgres refuses to
+--      drop a referenced type and renames update for free (the slug becomes
+--      display only — JOIN to entity_types for it).
+--
+--   2. Cross-org vocabulary. entity_types.id is globally unique (one sequence
+--      across all orgs), so an entity in tenant org A can carry a type defined
+--      in public-catalog org B by FK alone. No additional org_id column on
+--      entities is needed once the slug-based same-org coupling is gone.
+--
+-- Single-prod-DB migration: add nullable column, backfill, fail loudly on
+-- orphans, set NOT NULL, drop the text column. Run manually.
+
+-- 1. Add the FK column, nullable for backfill.
+ALTER TABLE public.entities
+    ADD COLUMN entity_type_id integer REFERENCES public.entity_types(id);
+
+-- 2. Backfill from existing (organization_id, entity_type slug) → entity_types.id.
+-- Prefer live entity_types rows; fall back to soft-deleted ones to preserve
+-- history. Without the ORDER BY, a slug+org pair with both an active and a
+-- soft-deleted row would resolve non-deterministically — entity_types' UNIQUE
+-- index on slug only covers `deleted_at IS NULL` rows, so collisions can exist.
+UPDATE public.entities e
+SET entity_type_id = (
+  SELECT et.id
+  FROM public.entity_types et
+  WHERE et.slug = e.entity_type
+    AND et.organization_id = e.organization_id
+  ORDER BY (et.deleted_at IS NULL) DESC, et.id DESC
+  LIMIT 1
+)
+WHERE e.entity_type_id IS NULL;
+
+-- 3. Fail loudly on orphans. If any entities reference a slug with no matching
+-- entity_types row, that's pre-existing data corruption from the slug-based
+-- regime. Surface it; don't paper over.
+DO $$
+DECLARE
+    orphan_count integer;
+BEGIN
+    SELECT COUNT(*) INTO orphan_count FROM public.entities WHERE entity_type_id IS NULL;
+    IF orphan_count > 0 THEN
+        RAISE EXCEPTION
+          'entity_type FK migration: % entities have entity_type slugs with no matching entity_types row. Investigate before re-running.',
+          orphan_count;
+    END IF;
+END $$;
+
+-- 4. Tighten the FK column.
+ALTER TABLE public.entities
+    ALTER COLUMN entity_type_id SET NOT NULL;
+
+-- 5. Index for filter/list queries that previously used entity_type slug.
+CREATE INDEX idx_entities_entity_type_id
+    ON public.entities (entity_type_id)
+    WHERE deleted_at IS NULL;
+
+-- 6. Drop the redundant UNIQUE constraint that referenced entity_type. The
+-- stronger `entities_slug_parent_unique` (UNIQUE on org_id, COALESCE(parent_id,
+-- 0), slug) already enforces slug uniqueness within (org, parent) regardless
+-- of entity type, with NULL-parent collapsing — so this constraint never
+-- caught anything the index didn't already catch. Drop it explicitly rather
+-- than letting DROP COLUMN cascade silently.
+ALTER TABLE public.entities
+    DROP CONSTRAINT IF EXISTS entities_organization_id_entity_type_slug_parent_id_key;
+
+-- 7. Drop the column comment so DROP COLUMN doesn't carry a stale doc string
+-- if this migration is ever rolled back and re-applied.
+COMMENT ON COLUMN public.entities.entity_type IS NULL;
+
+-- 8. Drop the text column. All readers JOIN to entity_types for the slug.
+ALTER TABLE public.entities DROP COLUMN entity_type;
+
+
+-- migrate:down
+
+ALTER TABLE public.entities ADD COLUMN entity_type text;
+
+UPDATE public.entities e
+SET entity_type = et.slug
+FROM public.entity_types et
+WHERE et.id = e.entity_type_id;
+
+ALTER TABLE public.entities ALTER COLUMN entity_type SET NOT NULL;
+
+COMMENT ON COLUMN public.entities.entity_type IS
+    'Type of entity: brand, product (future: location, feature, team)';
+
+ALTER TABLE public.entities
+    ADD CONSTRAINT entities_organization_id_entity_type_slug_parent_id_key
+    UNIQUE (organization_id, entity_type, slug, parent_id);
+
+DROP INDEX IF EXISTS public.idx_entities_entity_type_id;
+
+ALTER TABLE public.entities DROP COLUMN entity_type_id;

package/dist/db/migrations/20260426130000_db_integrity_cleanup.sql

@@ -0,0 +1,104 @@
+-- migrate:up
+
+-- DB integrity cleanup pass (transactional half).
+--
+-- This file groups the changes that are safe to run inside dbmate's default
+-- per-migration transaction: small-table tightenings and a UNIQUE swap that
+-- only takes a brief ACCESS EXCLUSIVE lock. Operations that would hold a
+-- long lock on busy tables (events.created_by NOT NULL, runs CHECK swap,
+-- connections UNIQUE) live in the companion `transaction:false` migration
+-- 20260426120001_db_integrity_cleanup_concurrent.sql.
+--
+-- Each tightening validates its precondition first and aborts loudly via
+-- RAISE EXCEPTION if dirty data is present, so a green run on staging is a
+-- strong signal for production.
+
+-- 1. Drop the legacy events archive (renamed during the append-only cutover
+--    on 2026-04-06; no application code references it).
+
+DROP TABLE IF EXISTS public.events_legacy_pre_append_only_20260406;
+
+-- 2. event_classifiers.status / organization_id -> NOT NULL.
+--    `status` already has DEFAULT 'active' but is nullable; backfill any
+--    pre-default rows then enforce. `organization_id` should never be null.
+
+UPDATE public.event_classifiers
+   SET status = 'active'
+ WHERE status IS NULL;
+
+DO $$
+DECLARE
+    null_org bigint;
+BEGIN
+    SELECT count(*) INTO null_org
+      FROM public.event_classifiers
+     WHERE organization_id IS NULL;
+    IF null_org > 0 THEN
+        RAISE EXCEPTION
+            'event_classifiers has % row(s) with NULL organization_id; backfill before re-running this migration',
+            null_org;
+    END IF;
+END$$;
+
+ALTER TABLE public.event_classifiers
+    ALTER COLUMN status SET NOT NULL,
+    ALTER COLUMN organization_id SET NOT NULL;
+
+-- 3. watchers.status / organization_id -> NOT NULL.
+--    `status` has DEFAULT 'active'; `organization_id` should never be null.
+
+UPDATE public.watchers
+   SET status = 'active'
+ WHERE status IS NULL;
+
+DO $$
+DECLARE
+    null_org bigint;
+BEGIN
+    SELECT count(*) INTO null_org
+      FROM public.watchers
+     WHERE organization_id IS NULL;
+    IF null_org > 0 THEN
+        RAISE EXCEPTION
+            'watchers has % row(s) with NULL organization_id; backfill before re-running this migration',
+            null_org;
+    END IF;
+END$$;
+
+ALTER TABLE public.watchers
+    ALTER COLUMN status SET NOT NULL,
+    ALTER COLUMN organization_id SET NOT NULL;
+
+-- 4. event_classifiers UNIQUE -> NULLS NOT DISTINCT.
+--    The previous (entity_id, watcher_id, slug) UNIQUE silently allowed
+--    duplicates whenever entity_id or watcher_id were NULL because Postgres
+--    treats NULLs as distinct. PG15+ supports NULLS NOT DISTINCT for the
+--    intended "one row per scope+slug" semantic.
+--    The table is small; the brief ACCESS EXCLUSIVE inside this transaction
+--    is acceptable.
+
+ALTER TABLE public.event_classifiers
+    DROP CONSTRAINT event_classifiers_unique_per_insight;
+
+ALTER TABLE public.event_classifiers
+    ADD CONSTRAINT event_classifiers_unique_per_insight
+        UNIQUE NULLS NOT DISTINCT (entity_id, watcher_id, slug);
+
+-- migrate:down
+
+ALTER TABLE public.event_classifiers
+    DROP CONSTRAINT event_classifiers_unique_per_insight;
+
+ALTER TABLE public.event_classifiers
+    ADD CONSTRAINT event_classifiers_unique_per_insight
+        UNIQUE (entity_id, watcher_id, slug);
+
+ALTER TABLE public.watchers
+    ALTER COLUMN organization_id DROP NOT NULL,
+    ALTER COLUMN status DROP NOT NULL;
+
+ALTER TABLE public.event_classifiers
+    ALTER COLUMN organization_id DROP NOT NULL,
+    ALTER COLUMN status DROP NOT NULL;
+
+-- The legacy events table is intentionally not recreated on rollback.

package/dist/db/migrations/20260426130001_db_integrity_cleanup_concurrent.sql

@@ -0,0 +1,187 @@
+-- migrate:up transaction:false
+
+-- DB integrity cleanup pass (non-transactional half).
+--
+-- Statements here would hold ACCESS EXCLUSIVE on busy tables for the
+-- duration of a table scan or index build if wrapped in dbmate's default
+-- per-migration transaction. Running with `transaction:false` lets each
+-- statement release its lock on completion so VALIDATE CONSTRAINT only
+-- needs SHARE UPDATE EXCLUSIVE (compatible with concurrent reads/writes)
+-- and CREATE INDEX CONCURRENTLY can do its non-blocking build.
+--
+-- All steps are written to be idempotent: re-running after a partial
+-- failure converges on the desired state. Validation aborts (RAISE
+-- EXCEPTION) leave the migration NOT applied so dbmate retries cleanly.
+--
+-- Set a short lock_timeout so any contention surfaces as a fast failure
+-- instead of a stuck deploy.
+SET lock_timeout = '5s';
+
+-- 1. events.created_by -> NOT NULL.
+--    ADD CHECK NOT VALID adds the catalog row under a brief ACCESS
+--    EXCLUSIVE without scanning the table. VALIDATE then takes only
+--    SHARE UPDATE EXCLUSIVE so concurrent reads/writes are unaffected.
+--    Once validated, SET NOT NULL is metadata-only because Postgres uses
+--    the validated CHECK as proof there are no NULLs (PG12+).
+
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1
+          FROM pg_constraint
+         WHERE conrelid = 'public.events'::regclass
+           AND conname = 'events_created_by_not_null'
+    ) THEN
+        ALTER TABLE public.events
+            ADD CONSTRAINT events_created_by_not_null
+                CHECK (created_by IS NOT NULL) NOT VALID;
+    END IF;
+END$$;
+
+-- Backfill historical NULLs with the existing 'system' sentinel before
+-- VALIDATE. Pre-`created_by` events end up here.
+--
+-- The session's lock_timeout is 5s (set at the top of this migration)
+-- which is appropriate for DDL but too aggressive for a row-level
+-- backfill running concurrently with live inserts: the deploying
+-- gateway and the live old pod can hold per-row locks briefly, and
+-- our UPDATE waits on each one. Bump locally for the UPDATE and the
+-- VALIDATE that follows, then restore.
+SET lock_timeout = 0;
+UPDATE public.events SET created_by = 'system' WHERE created_by IS NULL;
+
+ALTER TABLE public.events
+    VALIDATE CONSTRAINT events_created_by_not_null;
+
+ALTER TABLE public.events
+    ALTER COLUMN created_by SET NOT NULL;
+
+ALTER TABLE public.events
+    DROP CONSTRAINT IF EXISTS events_created_by_not_null;
+
+SET lock_timeout = '5s';
+
+-- 2. Prune historical run_type values from the runs CHECK.
+--    'embed_backfill' is still in active use and stays. 'insight' and
+--    'code' are remnants of earlier orchestration models with no
+--    production references; abort if any rows still carry them.
+--    Use the NOT VALID + VALIDATE pattern so the swap doesn't hold
+--    ACCESS EXCLUSIVE on runs across the table scan.
+
+DO $$
+DECLARE
+    historical bigint;
+BEGIN
+    SELECT count(*) INTO historical
+      FROM public.runs
+     WHERE run_type IN ('insight', 'code');
+    IF historical > 0 THEN
+        RAISE EXCEPTION
+            'runs has % row(s) with deprecated run_type (insight/code); migrate them before re-running',
+            historical;
+    END IF;
+END$$;
+
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1
+          FROM pg_constraint
+         WHERE conrelid = 'public.runs'::regclass
+           AND conname = 'runs_run_type_check_v2'
+    ) THEN
+        ALTER TABLE public.runs
+            ADD CONSTRAINT runs_run_type_check_v2
+                CHECK (run_type = ANY (ARRAY[
+                    'sync'::text,
+                    'action'::text,
+                    'embed_backfill'::text,
+                    'watcher'::text,
+                    'auth'::text
+                ])) NOT VALID;
+    END IF;
+END$$;
+
+ALTER TABLE public.runs
+    VALIDATE CONSTRAINT runs_run_type_check_v2;
+
+ALTER TABLE public.runs
+    DROP CONSTRAINT IF EXISTS runs_run_type_check;
+
+ALTER TABLE public.runs
+    RENAME CONSTRAINT runs_run_type_check_v2 TO runs_run_type_check;
+
+-- 3. Connections natural-key UNIQUE among live, authenticated rows.
+--    A reconnect should refresh credentials in place, not insert a new
+--    row. Partial index limits scope to non-deleted rows with an
+--    account_id so soft-deletes and unauthenticated stubs don't block
+--    re-creation. CONCURRENTLY avoids blocking writes during the build.
+
+DO $$
+DECLARE
+    dup_groups bigint;
+BEGIN
+    SELECT count(*) INTO dup_groups
+      FROM (
+        SELECT 1
+          FROM public.connections
+         WHERE deleted_at IS NULL
+           AND account_id IS NOT NULL
+         GROUP BY organization_id, connector_key, account_id
+        HAVING count(*) > 1
+      ) t;
+    IF dup_groups > 0 THEN
+        RAISE EXCEPTION
+            'connections has % duplicate (organization_id, connector_key, account_id) group(s) among live rows; dedupe before re-running',
+            dup_groups;
+    END IF;
+END$$;
+
+-- A previous failed run can leave an INVALID index behind. `IF NOT EXISTS`
+-- alone would skip creation in that case, leaving uniqueness unenforced.
+-- Drop first (no-op when the index doesn't exist) so the create always
+-- produces a valid index.
+--
+-- Originally CONCURRENTLY (which is why this migration is in the
+-- transaction:false half) but dbmate's transaction handling against
+-- the pq driver still presents these as in-transaction to Postgres,
+-- failing with "DROP INDEX CONCURRENTLY cannot run inside a
+-- transaction block". The connections table only has a handful of
+-- rows matching the partial-index predicate (≈2 in prod), so the
+-- ACCESS EXCLUSIVE held during a non-concurrent build is sub-second.
+DROP INDEX IF EXISTS public.idx_connections_org_connector_account_live;
+
+CREATE UNIQUE INDEX idx_connections_org_connector_account_live
+    ON public.connections (organization_id, connector_key, account_id)
+    WHERE deleted_at IS NULL AND account_id IS NOT NULL;
+
+-- migrate:down transaction:false
+
+DROP INDEX CONCURRENTLY IF EXISTS public.idx_connections_org_connector_account_live;
+
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1
+          FROM pg_constraint
+         WHERE conrelid = 'public.runs'::regclass
+           AND conname = 'runs_run_type_check'
+    ) THEN
+        ALTER TABLE public.runs DROP CONSTRAINT runs_run_type_check;
+    END IF;
+END$$;
+
+ALTER TABLE public.runs
+    ADD CONSTRAINT runs_run_type_check
+        CHECK (run_type = ANY (ARRAY[
+            'sync'::text,
+            'action'::text,
+            'code'::text,
+            'insight'::text,
+            'embed_backfill'::text,
+            'watcher'::text,
+            'auth'::text
+        ]));
+
+ALTER TABLE public.events
+    ALTER COLUMN created_by DROP NOT NULL;

package/dist/db/migrations/20260427133000_events_created_by_nullable.sql

@@ -0,0 +1,74 @@
+-- migrate:up transaction:false
+
+-- `events.created_by` represents the Lobu user that explicitly saved or
+-- authored an event. Connector/scheduled/system-produced events have no human
+-- saver; their provenance is represented by connector_key, connection_id,
+-- feed_id, run_id, and client_id. Keep user attribution nullable and enforce
+-- that any non-null value is a real user id instead of a sentinel string.
+SET lock_timeout = '5s';
+
+ALTER TABLE public.events
+    ALTER COLUMN created_by DROP NOT NULL;
+
+-- During a rolling deploy, old application pods may still write the historical
+-- 'system'/'api' sentinel actors. Normalize only those known sentinels to NULL
+-- before the FK sees them. Unknown non-user values should still be rejected.
+CREATE OR REPLACE FUNCTION public.normalize_event_created_by()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    IF NEW.created_by IN ('system', 'api') AND NOT EXISTS (
+        SELECT 1 FROM public."user" u WHERE u.id = NEW.created_by
+    ) THEN
+        NEW.created_by := NULL;
+    END IF;
+    RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS normalize_event_created_by ON public.events;
+CREATE TRIGGER normalize_event_created_by
+    BEFORE INSERT OR UPDATE OF created_by ON public.events
+    FOR EACH ROW
+    EXECUTE FUNCTION public.normalize_event_created_by();
+
+-- The previous integrity migration backfilled NULL event actors to 'system'.
+-- Convert those sentinel values back to NULL. This uses idx_events_created_by.
+SET lock_timeout = 0;
+UPDATE public.events e
+   SET created_by = NULL
+ WHERE e.created_by IN ('system', 'api')
+   AND NOT EXISTS (
+       SELECT 1 FROM public."user" u WHERE u.id = e.created_by
+   );
+SET lock_timeout = '5s';
+
+ALTER TABLE public.events
+    ADD CONSTRAINT events_created_by_fkey
+    FOREIGN KEY (created_by)
+    REFERENCES public."user"(id)
+    ON DELETE SET NULL
+    NOT VALID;
+
+SET lock_timeout = 0;
+ALTER TABLE public.events
+    VALIDATE CONSTRAINT events_created_by_fkey;
+SET lock_timeout = '5s';
+
+-- migrate:down transaction:false
+
+ALTER TABLE public.events
+    DROP CONSTRAINT IF EXISTS events_created_by_fkey;
+
+DROP TRIGGER IF EXISTS normalize_event_created_by ON public.events;
+DROP FUNCTION IF EXISTS public.normalize_event_created_by();
+
+SET lock_timeout = 0;
+UPDATE public.events
+   SET created_by = 'system'
+ WHERE created_by IS NULL;
+SET lock_timeout = '5s';
+
+ALTER TABLE public.events
+    ALTER COLUMN created_by SET NOT NULL;