@luanpdd/kit-mcp 1.20.0 → 1.22.0

package/kit/skills/multi-tenant-performance-scaling/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: multi-tenant-performance-scaling
+description: Use ao escalar Postgres multi-tenant em Supabase — Supavisor transaction mode (porta 6543), partial indexes obrigatórios em colunas de RLS, helper functions STABLE, partitioning por org_id quando >50k rows/tenant, MVs per-tenant para query caching.
+---
+
+# Multi-Tenant Performance & Scaling — Postgres + Supabase
+
+## Quando usar
+
+LLM carrega esta skill ao escalar app B2B multi-tenant em Supabase para alta carga (>1k req/s, >50k rows/tenant, >100 tenants ativos). Trigger phrases:
+
+- "Supavisor connection pooling", "transaction mode 6543"
+- "RLS performance multi-tenant", "helper function STABLE"
+- "partitioning por org_id", "particionamento Postgres tenant"
+- "materialized view per tenant", "MV per-tenant"
+- "scaling multi-tenant Postgres", "connection pool exhaustion"
+- "queries lentas multi-tenant"
+
+Esta skill é consumida por `multi-tenant-rls-writer` (Phase 108) ao gerar policies (índices acompanham), por `b2b-saas-architecture` (skill irmã) ao definir schema, e por `multi-tenant-isolation-auditor` ao auditar performance gaps.
+
+## Regras absolutas
+
+**REGRA #1 (connection pooling Vercel):** **SEMPRE** porta **6543** (Supavisor transaction mode) para Vercel Edge/Serverless. Porta 5432 (direct) só para long-running Node.js processes (workers, schedulers). Session mode na porta 6543 foi **deprecado em 2025-02-28** — não usar.
+
+**REGRA #2 (helper functions STABLE):** Funções PG usadas em RLS policies **DEVEM** ser marcadas `STABLE` (não `VOLATILE` que é o default). VOLATILE re-executa por linha — em tabela 100k rows = 100k chamadas extras.
+
+**REGRA #3 (partial indexes obrigatórios):** Cada coluna referenciada por RLS policy precisa de índice. Para multi-tenant, usar **partial indexes** em status='active' — exclui suspended/left que não são consultados em hot path.
+
+**REGRA #4 (partitioning threshold):** Particionar tabela por `org_id` (LIST partitioning) quando **>50k rows/tenant** OU **>100 tenants × 1k rows**. Abaixo disso, índices regulares são mais simples e performáticos.
+
+**REGRA #5 (MV refresh strategy):** Materialized Views per-tenant devem ter `REFRESH MATERIALIZED VIEW CONCURRENTLY` (não bloqueante) + `pg_cron` schedule. Refresh inline em request é anti-pattern.
+
+## Patterns canônicos
+
+### Supavisor — connection string Vercel
+
+```typescript
+// .env.local (Vercel) — porta 6543 SEMPRE
+DATABASE_URL="postgres://postgres.{project_ref}:{password}@aws-0-{region}.pooler.supabase.com:6543/postgres"
+
+// Para Prisma adicionar pgbouncer flag (Supavisor é compatível com pgbouncer protocol)
+DATABASE_URL="postgres://...:6543/postgres?pgbouncer=true&connection_limit=1"
+
+// Para long-running workers (cron jobs, BullMQ) usar 5432 direct connection
+WORKER_DATABASE_URL="postgres://postgres:{password}@db.{project_ref}.supabase.co:5432/postgres"
+```
+
+**Por que `connection_limit=1` com Prisma:** Supavisor é transaction-pooled — cada connection serverless deve ter `connection_limit=1` para não esgotar o pool no servidor.
+
+### Helper function STABLE — exemplo correto
+
+```sql
+-- STABLE — re-executa apenas 1× por query (Postgres pode cachear)
+create or replace function private.is_member_of(p_org_id uuid)
+returns boolean
+language sql
+stable                              -- ⭐ CRÍTICO — não VOLATILE
+security invoker
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.organization_members
+    where org_id = p_org_id
+      and user_id = (select auth.uid())
+      and status = 'active'
+  );
+$$;
+```
+
+**Diferença em produção:**
+- VOLATILE em policy SELECT em tabela 100k rows = 100k chamadas a `is_member_of` = ~10s query
+- STABLE em mesma policy = 1 chamada cacheada = ~50ms query
+- Speedup 200×
+
+### Partial indexes obrigatórios
+
+```sql
+-- Index parcial em organization_members (status='active' é hot path)
+create index organization_members_user_org_active_idx
+  on public.organization_members (user_id, org_id)
+  where status = 'active';
+
+-- Composite index em roles (lookup por nome dentro da org)
+create index roles_org_name_idx
+  on public.roles (org_id, name);
+
+-- Composite index em permissions (lookup por action+resource)
+create index permissions_action_resource_idx
+  on public.permissions (action, resource);
+
+-- Composite index em role_permissions (lookup por role)
+create index role_permissions_role_idx
+  on public.role_permissions (role_id);
+
+-- Index em departments (lookup por org)
+create index departments_org_idx
+  on public.departments (org_id);
+
+-- Index em audit_logs (sempre filtrar por tenant_id primeiro)
+create index audit_logs_tenant_created_idx
+  on public.audit_logs (tenant_id, created_at desc);
+```
+
+**Sem esses indexes, RLS força sequential scan a cada query** — degradação cresce linear com tamanho da tabela.
+
+### Partitioning por org_id (LIST partitioning)
+
+Aplicar quando **uma tabela** atinge >50k rows/tenant ou >5M total. Exemplo `audit_logs`:
+
+```sql
+-- Tabela particionada por LIST de org_id
+create table public.audit_logs (
+  id uuid not null,
+  tenant_id uuid not null,
+  event_type text not null,
+  actor_id uuid,
+  payload jsonb,
+  created_at timestamptz not null default now(),
+  primary key (id, tenant_id)
+) partition by list (tenant_id);
+
+-- Função que cria partição automaticamente para nova org
+create or replace function private.create_audit_partition(p_org_id uuid)
+returns void
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  partition_name text;
+begin
+  partition_name := 'audit_logs_' || replace(p_org_id::text, '-', '_');
+  execute format(
+    'create table if not exists public.%I partition of public.audit_logs for values in (%L)',
+    partition_name, p_org_id
+  );
+end;
+$$;
+
+-- Trigger em organizations: cria partição ao criar org
+create or replace function private.on_org_created()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+  perform private.create_audit_partition(new.id);
+  return new;
+end;
+$$;
+
+create trigger create_audit_partition_on_org_create
+  after insert on public.organizations
+  for each row execute function private.on_org_created();
+```
+
+**Quando NÃO particionar:**
+- <50k rows/tenant (overhead > benefit)
+- Queries cross-tenant frequentes (super-admin views) — partitioning torna isso lento
+- <100 tenants total (overhead > benefit)
+
+### Materialized Views per-tenant
+
+```sql
+-- MV agregando métricas por org (lead count, member count, etc.)
+create materialized view public.org_metrics as
+select
+  o.id as org_id,
+  o.name,
+  count(distinct om.user_id) filter (where om.status = 'active') as active_members,
+  count(distinct d.id) as departments_count,
+  max(om.joined_at) as last_member_joined
+from public.organizations o
+left join public.organization_members om on om.org_id = o.id
+left join public.departments d on d.org_id = o.id
+group by o.id, o.name;
+
+create unique index org_metrics_org_id_idx on public.org_metrics (org_id);
+
+-- Refresh CONCURRENT via pg_cron (não bloqueante)
+select cron.schedule(
+  'refresh-org-metrics',
+  '*/15 * * * *',  -- a cada 15min
+  $$ refresh materialized view concurrently public.org_metrics; $$
+);
+
+-- RLS sobre a MV (mesma policy de organizations)
+alter materialized view public.org_metrics enable row level security;
+
+create policy "org_metrics_select_member"
+  on public.org_metrics
+  for select
+  to authenticated
+  using (private.is_member_of(org_id));
+```
+
+**REFRESH CONCURRENTLY exige unique index** na MV (linha `unique index ... on public.org_metrics (org_id)` acima).
+
+### Diagnóstico de performance — queries canônicas
+
+```sql
+-- Top 10 queries lentas com RLS
+select
+  query,
+  calls,
+  mean_exec_time,
+  total_exec_time
+from pg_stat_statements
+where query ilike '%organization_members%'
+order by mean_exec_time desc
+limit 10;
+
+-- Tabelas sem index nas colunas de RLS
+select
+  c.relname as table_name,
+  pg_size_pretty(pg_total_relation_size(c.oid)) as size
+from pg_class c
+where c.relrowsecurity = true
+  and c.relkind = 'r'
+  and not exists (
+    select 1 from pg_index i
+    where i.indrelid = c.oid
+  );
+
+-- Connection pool usage (Supavisor)
+-- Verificar via Supabase Dashboard → Settings → Database → Connection Pooling
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Helper function VOLATILE (default)
+
+**Errado:**
+```sql
+create function private.is_member_of(p_org_id uuid)
+returns boolean
+language sql
+-- sem STABLE — default é VOLATILE
+as $$ select exists(...); $$;
+```
+
+**Por quê:** PG re-executa a função para CADA linha avaliada pela policy. Em tabela 100k rows, isso é 100k chamadas — cada uma com query interna ao banco. Latência cresce linearmente com tamanho da tabela.
+
+**Certo:** marcar `STABLE` (acima). PG executa 1× por query e cacheia o resultado para o restante das linhas.
+
+### Anti-pattern 2: Conexão direta porta 5432 em Vercel
+
+**Errado:**
+```typescript
+// Vercel Edge Function usando porta 5432 direct
+DATABASE_URL="postgres://...:5432/postgres"
+```
+
+**Por quê:** cada invocação Edge cria conexão direta ao Postgres. 100 req/s × 5 segundos = 500 conexões abertas simultaneamente. Postgres tem limite ~100 conns padrão — esgota → "too many connections" → 500 errors em produção.
+
+**Certo:** porta 6543 Supavisor transaction mode. Pool gerenciado por Supabase, conns recicladas após cada transaction.
+
+### Anti-pattern 3: Particionar tabela com poucos rows
+
+**Errado:**
+```sql
+-- App ainda em pre-launch, 5 tenants, 200 rows total
+create table public.events (...) partition by list (org_id);
+```
+
+**Por quê:** overhead de partition pruning + management > benefit. Cada query passa por partition routing, manutenção é complexa, dump/restore mais lento. Premature optimization clássica.
+
+**Certo:** começar com tabela regular + indexes. Particionar quando atingir threshold real (>50k rows/tenant).
+
+### Anti-pattern 4: MV refresh inline em request
+
+**Errado:**
+```typescript
+// Edge Function ao servir dashboard
+await supabase.rpc('refresh_org_metrics')  // 30s+ blocking!
+const metrics = await supabase.from('org_metrics').select()
+```
+
+**Por quê:** REFRESH MATERIALIZED VIEW (sem CONCURRENTLY) bloqueia a tabela. CONCURRENTLY não bloqueia mas leva tempo. Em request síncrono, user espera 30s.
+
+**Certo:** REFRESH CONCURRENTLY agendado por pg_cron. Request lê snapshot atual da MV (instantâneo).
+
+### Anti-pattern 5: Index full table quando partial cobre 90%
+
+**Errado:**
+```sql
+-- Index full sobre uma tabela onde 90% rows são status='left'
+create index members_user_idx on organization_members (user_id);
+```
+
+**Por quê:** index inclui rows inativas (status in ('suspended', 'left')) que não são consultadas em hot path. Tamanho do index 10× maior que necessário, refresh 10× mais lento.
+
+**Certo:**
+```sql
+create index members_user_active_idx
+  on organization_members (user_id, org_id)
+  where status = 'active';
+```
+
+Apenas rows ativas no index. Tamanho 10× menor, query plan idêntico em hot path.
+
+## Detecção e Mitigação de Tenant Quente (v1.22+)
+
+> Para detectar e mitigar o "tenant Justin Bieber" (1 tenant >>> outros), ver skill [`tenant-quente-mitigacao`](../tenant-quente-mitigacao/SKILL.md) (v1.22 — DDIA Ch 6). Cobre 3 métricas canônicas (queries/min, storage GB, conexões), 5 estratégias de mitigação (rate limit, pool isolado, replica dedicada, MV, request shaping), particionamento range vs hash para tenant_id, e rebalanceamento sem downtime.
+
+## Ver também
+
+- [b2b-saas-architecture](../b2b-saas-architecture/SKILL.md) — schema canônico que esta skill performance-otimiza (skill irmã)
+- [multi-tenant-rls-hierarchy](../multi-tenant-rls-hierarchy/SKILL.md) — helper functions PG (Phase 108) consumem REGRA #2 (STABLE)
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — `(select auth.uid())` wrapper já cobre 1 dimensão de performance (esta skill cobre as outras)
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — padrões PG functions (security invoker, search_path)
+- [supabase-cron-queues](../supabase-cron-queues/SKILL.md) — pg_cron usado em MV refresh schedule
+- [Supabase Supavisor 1M Connections](https://supabase.com/blog/supavisor-1-million)
+- [Supabase RLS Performance Best Practices](https://supabase.com/docs/guides/troubleshooting/rls-performance-and-best-practices-Z5Jjwv)
+- [Postgres LIST Partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE)

package/kit/skills/multi-tenant-rls-hierarchy/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: multi-tenant-rls-hierarchy
+description: Use ao escrever RLS hierárquica multi-tenant (org→dept→role→permission→super-admin bypass) em Supabase. 4 helper functions PG canônicas em schema private (STABLE), policies compostas com PERMISSIVE para super_admin, herança dept→org via coalesce.
+---
+
+# Multi-Tenant RLS Hierarchy — Helper Functions + Policies
+
+## Quando usar
+
+LLM carrega esta skill ao escrever RLS para tabelas em app B2B multi-tenant com hierarquia firm→department→leader→collaborator. Trigger phrases:
+
+- "RLS multi-tenant hierárquica", "RLS org dept role"
+- "helper function private", "is_member_of", "has_role", "has_permission", "is_super_admin"
+- "policy composta com super_admin bypass"
+- "department member herda role"
+- "PERMISSIVE policy super admin"
+
+Esta skill **estende** [`supabase-rls-policies`](../supabase-rls-policies/SKILL.md) (v1.8) — herda anti-pitfalls básicos (`(select auth.uid())` wrapper, no `user_metadata`, granular policies, indexes) e adiciona hierarquia + super_admin bypass.
+
+## Regras absolutas
+
+**REGRA #1 (helper functions em schema `private`):** Funções PG de RLS **DEVEM** estar em schema `private` — NÃO em `public`. PostgREST não expõe schema `private` automaticamente, então funções não viram endpoints REST acidentalmente.
+
+**REGRA #2 (STABLE marker obrigatório):** Helper functions usadas em policy **DEVEM** ser marcadas `STABLE` (não default `VOLATILE`). VOLATILE re-executa por linha — degradação de até 1000× em tabelas grandes.
+
+**REGRA #3 (security invoker + search_path = ''):** Helper functions **DEVEM** ter `security invoker` (default seguro) + `set search_path = ''` (previne search path injection).
+
+**REGRA #4 (super_admin via PERMISSIVE separada):** Bypass de super_admin **NÃO** é OR dentro da policy normal. É uma policy `as permissive` separada. PostgreSQL combina policies PERMISSIVE com OR — admin policy concedendo acesso = bypass total preservando granularidade.
+
+**REGRA #5 (herança dept→org via coalesce):** `department_members.role_id` NULL = herda do `organization_members.role_id` da mesma `(org, user)`. Resolução via função `private.effective_role_in_dept(p_dept_id, p_user_id)` que retorna `coalesce(dm.role_id, om.role_id)`.
+
+**REGRA #6 (todas anti-pitfalls v1.8 herdadas):** Aplicam-se SEMPRE — `(select auth.uid())` wrapper, NUNCA `user_metadata` em authz, 4 policies granulares (não `for all`), `to authenticated`/`to anon` explícito, indexes nas colunas das policies. Ver [`supabase-rls-policies`](../supabase-rls-policies/SKILL.md).
+
+## Patterns canônicos
+
+### 4 helper functions canônicas — DDL completo
+
+```sql
+-- Schema private (não exposto via PostgREST)
+create schema if not exists private;
+
+-- 1. is_member_of — checa se user é member ativo de uma org
+create or replace function private.is_member_of(p_org_id uuid)
+returns boolean
+language sql
+stable                        -- REGRA #2 — re-execução cacheada
+security invoker              -- REGRA #3 — usa permissões do caller
+set search_path = ''          -- REGRA #3 — previne injection
+as $$
+  select exists (
+    select 1 from public.organization_members
+    where org_id = p_org_id
+      and user_id = (select auth.uid())
+      and status = 'active'
+  );
+$$;
+
+-- 2. has_role — checa se user tem role específica numa org
+create or replace function private.has_role(p_org_id uuid, p_role_name text)
+returns boolean
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.organization_members om
+    join public.roles r on r.id = om.role_id
+    where om.org_id = p_org_id
+      and om.user_id = (select auth.uid())
+      and om.status = 'active'
+      and r.name = p_role_name
+  );
+$$;
+
+-- 3. has_permission — checa se user tem permission resource:action numa org
+create or replace function private.has_permission(p_action text, p_resource text, p_org_id uuid)
+returns boolean
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select exists (
+    select 1
+    from public.organization_members om
+    join public.role_permissions rp on rp.role_id = om.role_id
+    join public.permissions p on p.id = rp.permission_id
+    where om.org_id = p_org_id
+      and om.user_id = (select auth.uid())
+      and om.status = 'active'
+      and p.action = p_action
+      and p.resource = p_resource
+  );
+$$;
+
+-- 4. is_super_admin — checa flag em JWT app_metadata
+create or replace function private.is_super_admin()
+returns boolean
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select coalesce(
+    ((select auth.jwt())->'app_metadata'->>'super_admin')::boolean,
+    false
+  );
+$$;
+```
+
+**Indexes obrigatórios** (de [`multi-tenant-performance-scaling`](../multi-tenant-performance-scaling/SKILL.md)):
+
+```sql
+-- Partial index — REGRA #3 da skill performance
+create index if not exists organization_members_user_org_active_idx
+  on public.organization_members (user_id, org_id)
+  where status = 'active';
+
+create index if not exists role_permissions_role_idx
+  on public.role_permissions (role_id);
+
+create index if not exists permissions_action_resource_idx
+  on public.permissions (action, resource);
+```
+
+### Policy hierárquica composta — exemplo `leads`
+
+```sql
+-- Tabela leads multi-tenant
+create table public.leads (
+  id uuid primary key default gen_random_uuid(),
+  org_id uuid not null references public.organizations(id) on delete cascade,
+  dept_id uuid references public.departments(id) on delete set null,
+  contact_name text not null,
+  contact_email text,
+  contact_phone text,
+  stage text not null default 'lead' check (stage in ('lead','qualified','proposal','negotiation','won','lost')),
+  owner_id uuid references auth.users(id) on delete set null,
+  created_at timestamptz not null default now(),
+  unique (org_id, contact_email),
+  unique (org_id, contact_phone)
+);
+
+alter table public.leads enable row level security;
+
+-- POLICY 1: SELECT — member da org pode ler todos leads da org
+create policy "leads_select_member"
+  on public.leads
+  for select
+  to authenticated
+  using (private.is_member_of(org_id));
+
+-- POLICY 2: INSERT — member com permission leads:create
+create policy "leads_insert_with_permission"
+  on public.leads
+  for insert
+  to authenticated
+  with check (
+    private.has_permission('create', 'leads', org_id)
+  );
+
+-- POLICY 3: UPDATE — member com permission leads:update OU é owner do lead
+create policy "leads_update_with_permission_or_owner"
+  on public.leads
+  for update
+  to authenticated
+  using (
+    private.has_permission('update', 'leads', org_id)
+    or owner_id = (select auth.uid())
+  )
+  with check (
+    private.has_permission('update', 'leads', org_id)
+    or owner_id = (select auth.uid())
+  );
+
+-- POLICY 4: DELETE — apenas admin/owner role
+create policy "leads_delete_admin_owner"
+  on public.leads
+  for delete
+  to authenticated
+  using (
+    private.has_role(org_id, 'admin') or private.has_role(org_id, 'owner')
+  );
+
+-- POLICY 5 (PERMISSIVE — REGRA #4): super_admin bypass para todas operações
+create policy "leads_super_admin_bypass"
+  on public.leads
+  as permissive   -- combinação OR com policies normais
+  for all          -- super_admin pode tudo
+  to authenticated
+  using (private.is_super_admin())
+  with check (private.is_super_admin());
+
+-- Index obrigatório nas colunas filtradas
+create index leads_org_dept_idx on public.leads (org_id, dept_id);
+create index leads_owner_idx on public.leads (owner_id) where owner_id is not null;
+```
+
+### Herança dept→org — função `effective_role_in_dept`
+
+```sql
+-- 5. effective_role_in_dept — retorna role do user no contexto do dept
+-- (NULL em department_members.role_id = herda do organization_members)
+create or replace function private.effective_role_in_dept(p_dept_id uuid, p_user_id uuid)
+returns uuid
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select coalesce(dm.role_id, om.role_id)
+  from public.departments d
+  join public.organization_members om on om.org_id = d.org_id and om.user_id = p_user_id
+  left join public.department_members dm on dm.dept_id = p_dept_id and dm.user_id = p_user_id
+  where d.id = p_dept_id;
+$$;
+
+-- Helper: has_role no contexto de um dept (resolve herança)
+create or replace function private.has_role_in_dept(p_dept_id uuid, p_role_name text)
+returns boolean
+language sql
+stable
+security invoker
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.roles r
+    where r.id = private.effective_role_in_dept(p_dept_id, (select auth.uid()))
+      and r.name = p_role_name
+  );
+$$;
+```
+
+### Validar isolation via query — useful em testing
+
+```sql
+-- Listar tabelas com `org_id` mas SEM RLS habilitada (red flag)
+select c.relname
+from pg_class c
+join pg_attribute a on a.attrelid = c.oid
+where a.attname = 'org_id'
+  and c.relkind = 'r'
+  and c.relrowsecurity = false;
+
+-- Listar policies que referenciam helper functions canônicas
+select policyname, tablename, qual
+from pg_policies
+where qual like '%private.is_member_of%'
+   or qual like '%private.has_permission%'
+   or qual like '%private.is_super_admin%';
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Helper functions em `public` (expostos via PostgREST)
+
+**Errado:**
+```sql
+create function public.is_member_of(p_org_id uuid) returns boolean ...
+```
+
+**Por quê:** PostgREST expõe automaticamente `/rpc/is_member_of?p_org_id=...`. Endpoint vira público acessível, atacante pode probe quem é member de qual org.
+
+**Certo:** schema `private` (PostgREST ignora por default).
+
+### Anti-pattern 2: super_admin bypass via OR na policy normal
+
+**Errado:**
+```sql
+create policy "leads_select" on public.leads
+  for select
+  to authenticated
+  using (
+    private.is_member_of(org_id)
+    or private.is_super_admin()  -- bypass embutido
+  );
+```
+
+**Por quê:** funciona mas mistura semânticas. Mais difícil de auditar (qual é a "policy normal" vs "bypass"?). Mistura severidade — quando você desativar super_admin para teste, precisa editar todas as policies.
+
+**Certo:** policy `as permissive` separada para super_admin (REGRA #4). PostgreSQL faz OR entre policies PERMISSIVE.
+
+### Anti-pattern 3: Helper function VOLATILE (default)
+
+**Errado:**
+```sql
+create function private.is_member_of(p_org_id uuid)
+returns boolean
+language sql
+-- sem STABLE — default VOLATILE
+as $$ ... $$;
+```
+
+**Por quê:** ver [`multi-tenant-performance-scaling`](../multi-tenant-performance-scaling/SKILL.md) Anti-pattern 1. Re-execução por linha = degradação 200×.
+
+**Certo:** marcar `STABLE` (REGRA #2).
+
+### Anti-pattern 4: department_members sem coalesce — herança quebrada
+
+**Errado:**
+```sql
+-- Policy lê role direto de department_members, ignorando NULL
+using (
+  exists (
+    select 1 from public.department_members dm
+    join public.roles r on r.id = dm.role_id
+    where dm.user_id = (select auth.uid()) and r.name = 'admin'
+  )
+)
+```
+
+**Por quê:** se `dm.role_id IS NULL`, JOIN não casa, role efetiva não é resolvida → user adicionado ao dept sem role explícita não tem permissão (deveria herdar do org_members).
+
+**Certo:** usar `private.effective_role_in_dept` que faz coalesce.
+
+### Anti-pattern 5: super_admin sem audit log
+
+**Errado:**
+```sql
+-- super_admin policy permite ler/modificar tudo sem registrar quem foi
+create policy "super_admin_bypass" on public.leads as permissive for all to authenticated using (private.is_super_admin()) with check (private.is_super_admin());
+-- Mas... onde está o audit?
+```
+
+**Por quê:** super_admin sem audit = ninguém consegue investigar incident "quem deletou todos os leads da org X em 03/04?". Compliance LGPD exige audit de acesso a dados.
+
+**Certo:** policy super_admin OK, mas **toda operação super_admin** deve emitir evento `super_admin_action` em `audit_log` (Phase 109). Trigger AFTER INSERT/UPDATE/DELETE em tabelas críticas que checa `private.is_super_admin()` e registra.
+
+## Invariantes Linearizáveis Cross-Tenant (v1.22+)
+
+> Para uniqueness constraints cross-org (slug global, license key) e padrões `SELECT FOR UPDATE` em writes cross-tenant, ver skill [`escolha-modelo-consistencia`](../escolha-modelo-consistencia/SKILL.md) (v1.22 — DDIA Ch 9). Resumo: deixe `UNIQUE` constraint Postgres disparar via `INSERT ... ON CONFLICT DO NOTHING RETURNING` em vez de UPDATE+SELECT em nível de app (race window).
+
+## Ver também
+
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — anti-patterns base v1.8 herdados (REGRA #6)
+- [b2b-saas-architecture](../b2b-saas-architecture/SKILL.md) — schema canônico que esta skill cobre com RLS
+- [multi-tenant-performance-scaling](../multi-tenant-performance-scaling/SKILL.md) — STABLE marker + partial indexes (REGRA #2)
+- [rbac-permissions-matrix-supabase](../rbac-permissions-matrix-supabase/SKILL.md) — modelagem permissions consumed por `private.has_permission`
+- [super-admin-platform-pattern](../super-admin-platform-pattern/SKILL.md) — Phase 111, super_admin operations
+- [audit-log-multi-tenant](../audit-log-multi-tenant/SKILL.md) — Phase 109, audit `super_admin_action` (Anti-pattern 5)
+- [_shared-multi-tenant/glossary.md](../_shared-multi-tenant/glossary.md) — termos `RBAC`, `permission matrix`, `role escalation rule`