@opengeni/db 0.12.1 → 0.13.0

package/drizzle/0129_retained_process_reconciliation.sql

@@ -0,0 +1,356 @@
+-- deployment-mode: rolling
+-- Terminal owners do not prove provider quiescence. Persist only a
+-- bounded/fair reconciliation claim here; the worker must still obtain an exact
+-- provider exit/loss proof before invoking canonical retained-process settlement.
+
+ALTER TABLE "sandbox_retained_processes"
+  ADD COLUMN IF NOT EXISTS "reconcile_after" timestamptz NOT NULL DEFAULT now(),
+  ADD COLUMN IF NOT EXISTS "reconcile_claim_id" uuid,
+  ADD COLUMN IF NOT EXISTS "reconcile_claimed_at" timestamptz,
+  ADD COLUMN IF NOT EXISTS "reconcile_attempts" integer NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS "last_reconcile_outcome" text,
+  ADD COLUMN IF NOT EXISTS "reconcile_proof_outcome" text,
+  ADD COLUMN IF NOT EXISTS "reconcile_proof_exit_code" integer,
+  ADD COLUMN IF NOT EXISTS "reconcile_proof_reason" text,
+  ADD COLUMN IF NOT EXISTS "reconcile_proof_observed_at" timestamptz;
+
+ALTER TABLE "sandbox_retained_processes"
+  ADD CONSTRAINT "sandbox_retained_processes_reconcile_claim_check"
+  CHECK (
+    ("reconcile_claim_id" IS NULL AND "reconcile_claimed_at" IS NULL)
+    OR ("reconcile_claim_id" IS NOT NULL AND "reconcile_claimed_at" IS NOT NULL)
+  ),
+  ADD CONSTRAINT "sandbox_retained_processes_reconcile_attempts_check"
+  CHECK ("reconcile_attempts" >= 0),
+  ADD CONSTRAINT "sandbox_retained_processes_reconcile_outcome_check"
+  CHECK (
+    "last_reconcile_outcome" IS NULL
+    OR octet_length("last_reconcile_outcome") BETWEEN 1 AND 64
+  ),
+  ADD CONSTRAINT "sandbox_retained_processes_reconcile_proof_check"
+  CHECK (
+    (
+      "reconcile_proof_outcome" IS NULL
+      AND "reconcile_proof_exit_code" IS NULL
+      AND "reconcile_proof_reason" IS NULL
+      AND "reconcile_proof_observed_at" IS NULL
+    ) OR (
+      "reconcile_proof_outcome" = 'exited'
+      AND "reconcile_proof_exit_code" IS NOT NULL
+      AND "reconcile_proof_reason" = 'provider_exit_banner'
+      AND "reconcile_proof_observed_at" IS NOT NULL
+    ) OR (
+      "reconcile_proof_outcome" = 'lost'
+      AND "reconcile_proof_exit_code" IS NULL
+      AND "reconcile_proof_reason" IN (
+        'provider_session_lost_banner', 'provider_instance_not_found'
+      )
+      AND "reconcile_proof_observed_at" IS NOT NULL
+    )
+  );
+
+CREATE INDEX "sandbox_retained_processes_reconcile_due_idx"
+  ON "sandbox_retained_processes" ("reconcile_after", "started_at", "id")
+  WHERE "state" = 'active';
+
+CREATE INDEX "sandbox_retained_processes_active_inventory_idx"
+  ON "sandbox_retained_processes" (
+    "owner_actor_kind", "workspace_id", "owner_turn_id", "owner_attempt_id"
+  )
+  WHERE "state" = 'active';
+
+CREATE INDEX "sandbox_leases_expired_draining_inventory_idx"
+  ON "sandbox_leases" ("expires_at", "backend")
+  WHERE "liveness" = 'draining';
+
+-- The data schema is selected by the migration caller and may be public or a
+-- dedicated embed schema. Bind it into every privileged statement at creation
+-- time, then expose only pg_catalog at execution time. pg_temp and the caller's
+-- search_path can therefore resolve neither relations nor helper functions.
+DO $privileged_functions$
+DECLARE data_schema text := current_schema();
+BEGIN
+  -- The claim update fires this pre-existing deferred trigger while the claim
+  -- function's pg_catalog-only path is active. Replace its 0117 body in place so
+  -- the transitive identity check is equally independent of caller/pg_temp path.
+  EXECUTE format($create$
+    CREATE OR REPLACE FUNCTION opengeni_private.validate_sandbox_retained_process_v2()
+    RETURNS trigger
+    LANGUAGE plpgsql
+    SET search_path = pg_catalog
+    AS $function$
+    BEGIN
+      IF NOT EXISTS (
+        SELECT 1
+        FROM %1$I.sandbox_workspace_mutation_admissions admission
+        WHERE admission.id = NEW.parent_admission_id
+          AND admission.account_id = NEW.account_id
+          AND admission.workspace_id = NEW.workspace_id
+          AND admission.session_id = NEW.session_id
+          AND admission.lease_id = NEW.lease_id
+          AND admission.sandbox_group_id = NEW.sandbox_group_id
+          AND admission.actor_kind = NEW.owner_actor_kind
+          AND admission.actor_id = NEW.owner_actor_id
+          AND admission.turn_id IS NOT DISTINCT FROM NEW.owner_turn_id
+          AND admission.attempt_id IS NOT DISTINCT FROM NEW.owner_attempt_id
+          AND admission.execution_generation IS NOT DISTINCT FROM NEW.owner_execution_generation
+          AND admission.lease_epoch = NEW.lease_epoch
+          AND admission.provider_backend = NEW.provider_backend
+          AND admission.provider_instance_id = NEW.provider_instance_id
+          AND admission.route_kind = NEW.route_kind
+          AND admission.route_target_id IS NOT DISTINCT FROM NEW.route_target_id
+          AND admission.route_epoch = NEW.route_epoch
+          AND (
+            (
+              NEW.state = 'active'
+              AND admission.provider_outcome = 'retained'
+              AND admission.settled_at IS NULL
+              AND EXISTS (
+                SELECT 1 FROM %1$I.sandbox_lease_holders holder
+                WHERE holder.lease_id = NEW.lease_id
+                  AND holder.account_id = NEW.account_id
+                  AND holder.workspace_id = NEW.workspace_id
+                  AND holder.kind = 'process'
+                  AND holder.holder_id = NEW.holder_id
+                  AND holder.subject_id = NEW.session_id
+              )
+            ) OR (
+              NEW.state IN ('exited', 'lost')
+              AND admission.provider_outcome IN ('resolved', 'rejected')
+              AND admission.settled_at IS NOT NULL
+              AND NOT EXISTS (
+                SELECT 1 FROM %1$I.sandbox_lease_holders holder
+                WHERE holder.lease_id = NEW.lease_id
+                  AND holder.kind = 'process'
+                  AND holder.holder_id = NEW.holder_id
+              )
+              AND NOT EXISTS (
+                SELECT 1 FROM %1$I.sandbox_pty_sessions pty
+                WHERE pty.retained_process_id = NEW.id
+                  AND pty.status = 'open'
+              )
+            )
+          )
+      ) THEN
+        RAISE EXCEPTION 'retained process does not match its parent admission and holder state'
+          USING ERRCODE = '55000';
+      END IF;
+      RETURN NEW;
+    END;
+    $function$;
+  $create$, data_schema);
+
+  -- Cross-workspace claim for the sole control-worker reaper. The index-backed
+  -- candidate window is locked and limited before owner eligibility joins. A
+  -- live owner is deferred so it cannot permanently occupy the oldest due edge.
+  -- Claim expiry is represented by reconcile_after; it remains coordination
+  -- recovery only and is never physical-exit proof.
+  EXECUTE format($create$
+    CREATE OR REPLACE FUNCTION opengeni_private.claim_terminal_retained_processes(
+      p_claim_id uuid,
+      p_limit integer,
+      p_claim_ttl_ms bigint
+    )
+    RETURNS TABLE (
+      account_id uuid,
+      workspace_id uuid,
+      session_id uuid,
+      process_id uuid,
+      claim_id uuid,
+      owner_state text,
+      owner_attempt_outcome text
+    )
+    LANGUAGE plpgsql
+    SECURITY DEFINER
+    SET search_path = pg_catalog
+    AS $function$
+    BEGIN
+      IF p_limit < 1 OR p_limit > 100 THEN
+        RAISE EXCEPTION 'retained-process reconciliation limit must be between 1 and 100'
+          USING ERRCODE = '22023';
+      END IF;
+      IF p_claim_ttl_ms < 0 OR p_claim_ttl_ms > 3600000 THEN
+        RAISE EXCEPTION 'retained-process reconciliation claim TTL is invalid'
+          USING ERRCODE = '22023';
+      END IF;
+
+      PERFORM pg_catalog.set_config('opengeni.sandbox_recovery_protocol_v2', '1', true);
+
+      RETURN QUERY
+      WITH candidate_window AS MATERIALIZED (
+        SELECT process.id,
+          process.workspace_id,
+          process.owner_actor_kind,
+          process.owner_turn_id,
+          process.owner_attempt_id,
+          process.reconcile_after AS due_at,
+          process.started_at
+        FROM %1$I.sandbox_retained_processes process
+        WHERE process.state = 'active'
+          AND process.reconcile_after <= pg_catalog.now()
+        ORDER BY process.reconcile_after, process.started_at, process.id
+        FOR UPDATE OF process SKIP LOCKED
+        LIMIT p_limit
+      ), classified AS MATERIALIZED (
+        SELECT candidate.id,
+          candidate.due_at,
+          candidate.started_at,
+          candidate.owner_actor_kind = 'direct' OR attempt.state = 'closed' AS eligible,
+          CASE
+            WHEN candidate.owner_actor_kind = 'direct' THEN 'direct'
+            ELSE COALESCE(turn_row.status, 'missing')
+          END AS owner_state,
+          attempt.outcome AS owner_attempt_outcome
+        FROM candidate_window candidate
+        LEFT JOIN LATERAL (
+          SELECT source_turn.status
+          FROM %1$I.session_turns source_turn
+          WHERE source_turn.workspace_id = candidate.workspace_id
+            AND source_turn.id = candidate.owner_turn_id
+          LIMIT 1
+        ) turn_row ON true
+        LEFT JOIN LATERAL (
+          SELECT source_attempt.state, source_attempt.outcome
+          FROM %1$I.session_turn_attempts source_attempt
+          WHERE source_attempt.workspace_id = candidate.workspace_id
+            AND source_attempt.id = candidate.owner_attempt_id
+          LIMIT 1
+        ) attempt ON true
+      ), inspected AS (
+        UPDATE %1$I.sandbox_retained_processes process SET
+          reconcile_after = CASE
+            WHEN classified.eligible THEN pg_catalog.now()
+              + pg_catalog.make_interval(secs => p_claim_ttl_ms / 1000.0)
+            ELSE pg_catalog.now() + interval '30 seconds'
+          END,
+          reconcile_claim_id = CASE WHEN classified.eligible THEN p_claim_id ELSE NULL END,
+          reconcile_claimed_at = CASE
+            WHEN classified.eligible THEN pg_catalog.now() ELSE NULL
+          END,
+          reconcile_attempts = process.reconcile_attempts
+            + CASE WHEN classified.eligible THEN 1 ELSE 0 END,
+          last_reconcile_outcome = CASE
+            WHEN classified.eligible THEN 'claimed' ELSE 'owner_active'
+          END
+        FROM classified
+        WHERE process.id = classified.id
+          AND process.state = 'active'
+        RETURNING process.account_id,
+          process.workspace_id,
+          process.session_id,
+          process.id,
+          process.reconcile_claim_id,
+          classified.due_at,
+          classified.started_at,
+          classified.eligible,
+          classified.owner_state,
+          classified.owner_attempt_outcome
+      )
+      SELECT inspected.account_id,
+        inspected.workspace_id,
+        inspected.session_id,
+        inspected.id,
+        inspected.reconcile_claim_id,
+        inspected.owner_state,
+        inspected.owner_attempt_outcome
+      FROM inspected
+      WHERE inspected.eligible
+      ORDER BY inspected.due_at, inspected.started_at, inspected.id;
+
+      -- Fire the exact data-schema constraint trigger while the definer still
+      -- owns cross-workspace visibility, then restore deferred mode.
+      SET CONSTRAINTS %1$I.sandbox_retained_processes_identity_v2 IMMEDIATE;
+      SET CONSTRAINTS %1$I.sandbox_retained_processes_identity_v2 DEFERRED;
+    END;
+    $function$;
+  $create$, data_schema);
+
+  -- Fixed-shape global inventories use covering partial indexes over only the
+  -- active/draining subsets; retained history and cold/warm lease inventory are
+  -- not scanned by a reaper tick. The application normalizes legacy values into
+  -- its finite label sets.
+  EXECUTE format($create$
+    CREATE OR REPLACE FUNCTION opengeni_private.count_active_retained_processes_by_owner_state()
+    RETURNS TABLE (owner_state text, active_count bigint, terminal_owner_count bigint)
+    LANGUAGE sql
+    SECURITY DEFINER
+    SET search_path = pg_catalog
+    AS $function$
+      SELECT inventory.owner_state,
+        pg_catalog.count(*)::bigint AS active_count,
+        pg_catalog.count(*) FILTER (WHERE inventory.terminal_owner)::bigint
+          AS terminal_owner_count
+      FROM (
+        SELECT 'direct'::text AS owner_state, true AS terminal_owner
+        FROM %1$I.sandbox_retained_processes process
+        WHERE process.state = 'active'
+          AND process.owner_actor_kind = 'direct'
+        UNION ALL
+        SELECT COALESCE(turn_row.status, 'missing') AS owner_state,
+          attempt.state = 'closed' AS terminal_owner
+        FROM %1$I.sandbox_retained_processes process
+        LEFT JOIN LATERAL (
+          SELECT source_turn.status
+          FROM %1$I.session_turns source_turn
+          WHERE source_turn.workspace_id = process.workspace_id
+            AND source_turn.id = process.owner_turn_id
+          LIMIT 1
+        ) turn_row ON true
+        LEFT JOIN LATERAL (
+          SELECT source_attempt.state
+          FROM %1$I.session_turn_attempts source_attempt
+          WHERE source_attempt.workspace_id = process.workspace_id
+            AND source_attempt.id = process.owner_attempt_id
+          LIMIT 1
+        ) attempt ON true
+        WHERE process.state = 'active'
+          AND process.owner_actor_kind = 'turn'
+      ) inventory
+      GROUP BY inventory.owner_state;
+    $function$;
+  $create$, data_schema);
+
+  EXECUTE format($create$
+    CREATE OR REPLACE FUNCTION opengeni_private.count_expired_draining_sandbox_leases()
+    RETURNS TABLE (backend text, age_bucket text, count bigint)
+    LANGUAGE sql
+    SECURITY DEFINER
+    SET search_path = pg_catalog
+    AS $function$
+      SELECT lease.backend,
+        CASE
+          WHEN pg_catalog.now() - lease.expires_at < interval '5 minutes' THEN 'lt_5m'
+          WHEN pg_catalog.now() - lease.expires_at < interval '1 hour' THEN '5m_1h'
+          WHEN pg_catalog.now() - lease.expires_at < interval '1 day' THEN '1h_1d'
+          ELSE 'gte_1d'
+        END AS age_bucket,
+        pg_catalog.count(*)::bigint
+      FROM %1$I.sandbox_leases lease
+      WHERE lease.liveness = 'draining'
+        AND lease.expires_at < pg_catalog.now()
+      GROUP BY lease.backend, age_bucket;
+    $function$;
+  $create$, data_schema);
+END $privileged_functions$;
+
+-- PostgreSQL grants new functions to PUBLIC by default. These functions bypass
+-- workspace RLS, so only the migration owner and explicit application role may
+-- execute them.
+REVOKE ALL ON FUNCTION opengeni_private.claim_terminal_retained_processes(uuid, integer, bigint)
+  FROM PUBLIC;
+REVOKE ALL ON FUNCTION opengeni_private.count_active_retained_processes_by_owner_state()
+  FROM PUBLIC;
+REVOKE ALL ON FUNCTION opengeni_private.count_expired_draining_sandbox_leases()
+  FROM PUBLIC;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT EXECUTE ON FUNCTION opengeni_private.claim_terminal_retained_processes(uuid, integer, bigint)
+      TO opengeni_app;
+    GRANT EXECUTE ON FUNCTION opengeni_private.count_active_retained_processes_by_owner_state()
+      TO opengeni_app;
+    GRANT EXECUTE ON FUNCTION opengeni_private.count_expired_draining_sandbox_leases()
+      TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0130_workspace_instruction_policies.sql

@@ -0,0 +1,330 @@
+-- deployment-mode: rolling
+-- Backend-only workspace instruction-policy foundation. This migration performs no
+-- backfill: workspaces without an activation head retain legacy behavior.
+
+CREATE SEQUENCE IF NOT EXISTS "workspace_instruction_policy_revision_seq" AS bigint;
+
+CREATE TABLE IF NOT EXISTS "workspace_instruction_policy_revisions" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "account_id" uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id" uuid NOT NULL REFERENCES "workspaces"("id") ON DELETE CASCADE,
+  "revision" bigint NOT NULL DEFAULT nextval('workspace_instruction_policy_revision_seq'),
+  "kind" text NOT NULL,
+  "scope" text NOT NULL,
+  "role_key" text,
+  "content" text NOT NULL,
+  "content_hash" text NOT NULL,
+  "provenance_source" text NOT NULL,
+  "provenance_source_id" text,
+  "supersedes_revision_id" uuid REFERENCES "workspace_instruction_policy_revisions"("id") ON DELETE RESTRICT,
+  "created_by_subject_id" text NOT NULL,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "workspace_instruction_policy_revisions_revision_chk" CHECK ("revision" > 0),
+  CONSTRAINT "workspace_instruction_policy_revisions_target_chk" CHECK (
+    ("kind" = 'charter' AND "scope" = 'global' AND "role_key" IS NULL)
+    OR ("kind" = 'policy' AND "scope" = 'global' AND "role_key" IS NULL)
+    OR ("kind" = 'policy' AND "scope" = 'role' AND "role_key" IS NOT NULL)
+  ),
+  CONSTRAINT "workspace_instruction_policy_revisions_role_key_chk" CHECK (
+    "role_key" IS NULL
+    OR (
+      "role_key" = lower(btrim("role_key"))
+      AND length("role_key") BETWEEN 1 AND 64
+      AND "role_key" ~ '^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$'
+      AND "role_key" !~ '--'
+    )
+  ),
+  CONSTRAINT "workspace_instruction_policy_revisions_content_chk" CHECK (
+    length(btrim("content")) > 0 AND octet_length("content") <= 1048576
+  ),
+  CONSTRAINT "workspace_instruction_policy_revisions_hash_chk" CHECK (
+    "content_hash" ~ '^[0-9a-f]{64}$'
+    AND "content_hash" = encode(sha256(convert_to("content", 'UTF8')), 'hex')
+  ),
+  CONSTRAINT "workspace_instruction_policy_revisions_provenance_chk" CHECK (
+    "provenance_source" IN ('human', 'onboarding', 'knowledge_proposal', 'legacy_import')
+    AND ("provenance_source_id" IS NULL OR length("provenance_source_id") BETWEEN 1 AND 512)
+  ),
+  CONSTRAINT "workspace_instruction_policy_revisions_actor_chk" CHECK (
+    length(btrim("created_by_subject_id")) BETWEEN 1 AND 1024
+  ),
+  CONSTRAINT "workspace_instruction_policy_revisions_workspace_revision_uq"
+    UNIQUE ("workspace_id", "revision")
+);
+
+CREATE INDEX IF NOT EXISTS "workspace_instruction_policy_revisions_workspace_history_idx"
+  ON "workspace_instruction_policy_revisions"
+  ("workspace_id", "kind", "scope", "role_key", "revision" DESC);
+
+CREATE TABLE IF NOT EXISTS "workspace_instruction_policy_heads" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "account_id" uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id" uuid NOT NULL REFERENCES "workspaces"("id") ON DELETE CASCADE,
+  "kind" text NOT NULL,
+  "scope" text NOT NULL,
+  "role_key" text,
+  "revision_id" uuid NOT NULL REFERENCES "workspace_instruction_policy_revisions"("id") ON DELETE RESTRICT,
+  "revision" bigint NOT NULL,
+  "content_hash" text NOT NULL,
+  "activation_version" bigint NOT NULL,
+  "activated_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "workspace_instruction_policy_heads_target_chk" CHECK (
+    ("kind" = 'charter' AND "scope" = 'global' AND "role_key" IS NULL)
+    OR ("kind" = 'policy' AND "scope" = 'global' AND "role_key" IS NULL)
+    OR ("kind" = 'policy' AND "scope" = 'role' AND "role_key" IS NOT NULL)
+  ),
+  CONSTRAINT "workspace_instruction_policy_heads_role_key_chk" CHECK (
+    "role_key" IS NULL
+    OR (
+      "role_key" = lower(btrim("role_key"))
+      AND length("role_key") BETWEEN 1 AND 64
+      AND "role_key" ~ '^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$'
+      AND "role_key" !~ '--'
+    )
+  ),
+  CONSTRAINT "workspace_instruction_policy_heads_revision_chk" CHECK (
+    "revision" > 0 AND "activation_version" > 0 AND "content_hash" ~ '^[0-9a-f]{64}$'
+  )
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "workspace_instruction_policy_heads_charter_uq"
+  ON "workspace_instruction_policy_heads" ("workspace_id")
+  WHERE "kind" = 'charter';
+
+CREATE UNIQUE INDEX IF NOT EXISTS "workspace_instruction_policy_heads_global_policy_uq"
+  ON "workspace_instruction_policy_heads" ("workspace_id")
+  WHERE "kind" = 'policy' AND "scope" = 'global';
+
+CREATE UNIQUE INDEX IF NOT EXISTS "workspace_instruction_policy_heads_role_policy_uq"
+  ON "workspace_instruction_policy_heads" ("workspace_id", "role_key")
+  WHERE "kind" = 'policy' AND "scope" = 'role';
+
+CREATE TABLE IF NOT EXISTS "workspace_instruction_policy_activation_events" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "account_id" uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id" uuid NOT NULL REFERENCES "workspaces"("id") ON DELETE CASCADE,
+  "kind" text NOT NULL,
+  "scope" text NOT NULL,
+  "role_key" text,
+  "type" text NOT NULL,
+  "activation_version" bigint NOT NULL,
+  "old_revision_id" uuid REFERENCES "workspace_instruction_policy_revisions"("id") ON DELETE RESTRICT,
+  "old_revision" bigint,
+  "old_content_hash" text,
+  "new_revision_id" uuid NOT NULL REFERENCES "workspace_instruction_policy_revisions"("id") ON DELETE RESTRICT,
+  "new_revision" bigint NOT NULL,
+  "new_content_hash" text NOT NULL,
+  "actor_subject_id" text NOT NULL,
+  "reason" text NOT NULL,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "workspace_instruction_policy_activation_events_type_chk" CHECK (
+    "type" IN ('activate', 'rollback')
+  ),
+  CONSTRAINT "workspace_instruction_policy_activation_events_target_chk" CHECK (
+    ("kind" = 'charter' AND "scope" = 'global' AND "role_key" IS NULL)
+    OR ("kind" = 'policy' AND "scope" = 'global' AND "role_key" IS NULL)
+    OR ("kind" = 'policy' AND "scope" = 'role' AND "role_key" IS NOT NULL)
+  ),
+  CONSTRAINT "workspace_instruction_policy_activation_events_role_key_chk" CHECK (
+    "role_key" IS NULL
+    OR (
+      "role_key" = lower(btrim("role_key"))
+      AND length("role_key") BETWEEN 1 AND 64
+      AND "role_key" ~ '^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$'
+      AND "role_key" !~ '--'
+    )
+  ),
+  CONSTRAINT "workspace_instruction_policy_activation_events_old_revision_chk" CHECK (
+    ("old_revision_id" IS NULL AND "old_revision" IS NULL AND "old_content_hash" IS NULL)
+    OR (
+      "old_revision_id" IS NOT NULL
+      AND "old_revision" > 0
+      AND "old_content_hash" ~ '^[0-9a-f]{64}$'
+    )
+  ),
+  CONSTRAINT "workspace_instruction_policy_activation_events_new_revision_chk" CHECK (
+    "new_revision" > 0
+    AND "new_content_hash" ~ '^[0-9a-f]{64}$'
+    AND "activation_version" > 0
+  ),
+  CONSTRAINT "workspace_instruction_policy_activation_events_audit_chk" CHECK (
+    length(btrim("actor_subject_id")) BETWEEN 1 AND 1024
+    AND length(btrim("reason")) BETWEEN 1 AND 4096
+  )
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "workspace_instruction_policy_events_target_version_uq"
+  ON "workspace_instruction_policy_activation_events"
+  ("workspace_id", "kind", "scope", coalesce("role_key", ''), "activation_version");
+
+CREATE INDEX IF NOT EXISTS "workspace_instruction_policy_events_workspace_time_idx"
+  ON "workspace_instruction_policy_activation_events" ("workspace_id", "created_at" DESC, "id");
+
+CREATE OR REPLACE FUNCTION workspace_instruction_policy_validate_revision_link()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  target_workspace_id uuid;
+  target_kind text;
+  target_scope text;
+  target_role_key text;
+BEGIN
+  IF NEW."supersedes_revision_id" IS NULL THEN
+    RETURN NEW;
+  END IF;
+  SELECT "workspace_id", "kind", "scope", "role_key"
+    INTO target_workspace_id, target_kind, target_scope, target_role_key
+    FROM "workspace_instruction_policy_revisions"
+    WHERE "id" = NEW."supersedes_revision_id";
+  IF NOT FOUND
+    OR target_workspace_id IS DISTINCT FROM NEW."workspace_id"
+    OR target_kind IS DISTINCT FROM NEW."kind"
+    OR target_scope IS DISTINCT FROM NEW."scope"
+    OR target_role_key IS DISTINCT FROM NEW."role_key"
+  THEN
+    RAISE EXCEPTION 'superseded instruction-policy revision must use the same workspace and target'
+      USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS workspace_instruction_policy_revisions_validate_link
+  ON "workspace_instruction_policy_revisions";
+CREATE TRIGGER workspace_instruction_policy_revisions_validate_link
+  BEFORE INSERT OR UPDATE ON "workspace_instruction_policy_revisions"
+  FOR EACH ROW EXECUTE FUNCTION workspace_instruction_policy_validate_revision_link();
+
+CREATE OR REPLACE FUNCTION workspace_instruction_policy_validate_head()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM "workspace_instruction_policy_revisions" revision
+    WHERE revision."id" = NEW."revision_id"
+      AND revision."account_id" = NEW."account_id"
+      AND revision."workspace_id" = NEW."workspace_id"
+      AND revision."kind" = NEW."kind"
+      AND revision."scope" = NEW."scope"
+      AND revision."role_key" IS NOT DISTINCT FROM NEW."role_key"
+      AND revision."revision" = NEW."revision"
+      AND revision."content_hash" = NEW."content_hash"
+  ) THEN
+    RAISE EXCEPTION 'instruction-policy head must identify an exact target revision'
+      USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS workspace_instruction_policy_heads_validate_revision
+  ON "workspace_instruction_policy_heads";
+CREATE TRIGGER workspace_instruction_policy_heads_validate_revision
+  BEFORE INSERT OR UPDATE ON "workspace_instruction_policy_heads"
+  FOR EACH ROW EXECUTE FUNCTION workspace_instruction_policy_validate_head();
+
+CREATE OR REPLACE FUNCTION workspace_instruction_policy_validate_event()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM "workspace_instruction_policy_revisions" revision
+    WHERE revision."id" = NEW."new_revision_id"
+      AND revision."account_id" = NEW."account_id"
+      AND revision."workspace_id" = NEW."workspace_id"
+      AND revision."kind" = NEW."kind"
+      AND revision."scope" = NEW."scope"
+      AND revision."role_key" IS NOT DISTINCT FROM NEW."role_key"
+      AND revision."revision" = NEW."new_revision"
+      AND revision."content_hash" = NEW."new_content_hash"
+  ) THEN
+    RAISE EXCEPTION 'instruction-policy activation event has an invalid new revision'
+      USING ERRCODE = '23514';
+  END IF;
+  IF NEW."old_revision_id" IS NOT NULL AND NOT EXISTS (
+    SELECT 1
+    FROM "workspace_instruction_policy_revisions" revision
+    WHERE revision."id" = NEW."old_revision_id"
+      AND revision."account_id" = NEW."account_id"
+      AND revision."workspace_id" = NEW."workspace_id"
+      AND revision."kind" = NEW."kind"
+      AND revision."scope" = NEW."scope"
+      AND revision."role_key" IS NOT DISTINCT FROM NEW."role_key"
+      AND revision."revision" = NEW."old_revision"
+      AND revision."content_hash" = NEW."old_content_hash"
+  ) THEN
+    RAISE EXCEPTION 'instruction-policy activation event has an invalid old revision'
+      USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS workspace_instruction_policy_events_validate_revisions
+  ON "workspace_instruction_policy_activation_events";
+CREATE TRIGGER workspace_instruction_policy_events_validate_revisions
+  BEFORE INSERT OR UPDATE ON "workspace_instruction_policy_activation_events"
+  FOR EACH ROW EXECUTE FUNCTION workspace_instruction_policy_validate_event();
+
+CREATE OR REPLACE FUNCTION workspace_instruction_policy_reject_mutation()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  -- PostgreSQL implements ON DELETE CASCADE with a parent constraint trigger.
+  -- By the time that trigger deletes child rows, the workspace is absent and
+  -- this child trigger is nested. Require both facts so direct history deletes
+  -- and deletes issued by unrelated triggers remain fail-closed.
+  IF TG_OP = 'DELETE'
+    AND pg_trigger_depth() > 1
+    AND NOT EXISTS (
+      SELECT 1
+      FROM "workspaces" workspace
+      WHERE workspace."id" = OLD."workspace_id"
+    )
+  THEN
+    RETURN OLD;
+  END IF;
+  RAISE EXCEPTION 'workspace instruction-policy history is immutable'
+    USING ERRCODE = '55000';
+END;
+$$;
+
+DROP TRIGGER IF EXISTS workspace_instruction_policy_revisions_immutable
+  ON "workspace_instruction_policy_revisions";
+CREATE TRIGGER workspace_instruction_policy_revisions_immutable
+  BEFORE UPDATE OR DELETE ON "workspace_instruction_policy_revisions"
+  FOR EACH ROW EXECUTE FUNCTION workspace_instruction_policy_reject_mutation();
+
+DROP TRIGGER IF EXISTS workspace_instruction_policy_events_immutable
+  ON "workspace_instruction_policy_activation_events";
+CREATE TRIGGER workspace_instruction_policy_events_immutable
+  BEFORE UPDATE OR DELETE ON "workspace_instruction_policy_activation_events"
+  FOR EACH ROW EXECUTE FUNCTION workspace_instruction_policy_reject_mutation();
+
+ALTER TABLE "workspace_instruction_policy_revisions" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "workspace_instruction_policy_revisions" FORCE ROW LEVEL SECURITY;
+ALTER TABLE "workspace_instruction_policy_heads" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "workspace_instruction_policy_heads" FORCE ROW LEVEL SECURITY;
+ALTER TABLE "workspace_instruction_policy_activation_events" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "workspace_instruction_policy_activation_events" FORCE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS workspace_isolation ON "workspace_instruction_policy_revisions";
+CREATE POLICY workspace_isolation ON "workspace_instruction_policy_revisions"
+  USING (opengeni_private.workspace_rls_visible("account_id", "workspace_id"))
+  WITH CHECK (opengeni_private.workspace_rls_visible("account_id", "workspace_id"));
+
+DROP POLICY IF EXISTS workspace_isolation ON "workspace_instruction_policy_heads";
+CREATE POLICY workspace_isolation ON "workspace_instruction_policy_heads"
+  USING (opengeni_private.workspace_rls_visible("account_id", "workspace_id"))
+  WITH CHECK (opengeni_private.workspace_rls_visible("account_id", "workspace_id"));
+
+DROP POLICY IF EXISTS workspace_isolation ON "workspace_instruction_policy_activation_events";
+CREATE POLICY workspace_isolation ON "workspace_instruction_policy_activation_events"
+  USING (opengeni_private.workspace_rls_visible("account_id", "workspace_id"))
+  WITH CHECK (opengeni_private.workspace_rls_visible("account_id", "workspace_id"));