@fayz-ai/db 0.13.0 → 0.14.0

package/migrations/016_the_rule_stops_asking_every_row.sql

@@ -0,0 +1,543 @@
+-- ---------------------------------------------------------------------------
+-- 016_the_rule_stops_asking_every_row.sql — a list of 3.545 clientes stops
+-- costing 3.545 answers to the same question.
+--
+-- THE BUG, as seen: `/clients` no Espaço Facial não carrega. Não é lentidão —
+-- é o teto de 8s do papel `authenticated` estourando, e a tela dizendo "não foi
+-- possível carregar" sem nenhuma linha. A 3.545 clientes o tenant é o primeiro
+-- de escala real da rede; nos outros a mesma consulta responde em milissegundos
+-- e nada disto aparece.
+--
+-- O QUE O PLANEJADOR DIZ (EXPLAIN ANALYZE, 50 linhas, ordenado por nome):
+--
+--     Limit                                        actual time=10034
+--       Index Scan using people_tenant_kind        rows=3545
+--         SubPlan 1  (available_in_my_units)       2.471ms  × 3545 = 8.760s
+--         SubPlan 8  (has_permission)              0.333ms  × 3545 = 1.180s
+--         Execution Time: 10035 ms
+--
+-- Duas perguntas feitas UMA VEZ POR LINHA, e as duas com a mesma resposta em
+-- todas elas.
+--
+-- ── A primeira: a regra de distribuição ────────────────────────────────────
+-- `people_available_in` chama `app.available_in_my_units('people.person', id)`
+-- para cada linha sem unidade. A função monta quatro CTEs, resolve a cadeia de
+-- cada unidade do chamador e cruza com `app.resource_grants` — para descobrir,
+-- 3.545 vezes seguidas, que ESTE TENANT NÃO TEM NENHUMA REGRA DE DISTRIBUIÇÃO.
+-- São zero tuplas no banco inteiro fora uma.
+--
+-- E quando não há tupla, a resposta é conhecida sem olhar linha nenhuma. Com
+-- `tup` vazio o corpo da função reduz a:
+--
+--     NOT EXISTS(direct unavailable_in)            -- vazio  ⇒ true
+--     AND ( EXISTS(direct available_in)            -- vazio  ⇒ false
+--        OR EXISTS(verdicts allow)                 -- 'none' ⇒ false
+--        OR ( NOT EXISTS(tup available_in)         -- vazio  ⇒ true
+--             AND (EXISTS(verdicts 'none') OR NOT EXISTS(mine)) ) )
+--
+-- O último parêntese é verdade nos dois casos possíveis: com unidades, todo
+-- veredito é 'none'; sem unidades, `NOT EXISTS(mine)`. Logo: sem tupla do tipo
+-- no tenant, a função devolve `true` para TODA linha. Isso não é uma
+-- aproximação — é o mesmo valor, e é por isso que dá para perguntar uma vez.
+--
+-- A pergunta barata — "este tenant tem alguma regra deste tipo?" — não depende
+-- da linha, então o planejador a promove a InitPlan e ela roda UMA vez. Só
+-- quando a resposta é sim é que a função cara volta a ser chamada, e aí ela é o
+-- preço correto de um recurso que realmente foi distribuído.
+--
+-- ── A segunda: a permissão ─────────────────────────────────────────────────
+-- `(select app.has_permission('people.read', unit_id))` correlaciona pela
+-- coluna, então roda por linha — inclusive nas linhas em que `unit_id` é NULL,
+-- onde `effective_role_id` ignora a unidade e a resposta é sempre a mesma.
+--
+-- Separar os dois casos num CASE resolve sem mudar o resultado: o ramo do NULL
+-- não menciona coluna nenhuma, vira InitPlan, e roda uma vez para a consulta
+-- inteira. O ramo da unidade continua exatamente como era. Verificado no
+-- planejador: `Filter: CASE WHEN (unit_id IS NULL) THEN (InitPlan 1).col1 ELSE
+-- (SubPlan 2) END`, com o SubPlan `never executed`.
+--
+-- ── E a terceira, que ainda não doeu ───────────────────────────────────────
+-- `app.has_grant(tipo, id, 'shared_with')` no predicado de escopo é a mesma
+-- armadilha, só que adormecida: ela só não custa hoje porque `owner_id IS NULL`
+-- curto-circuita o OR antes dela. Numa tabela com dono preenchido ela roda por
+-- linha, com a mesma resposta constante. Ganha a mesma guarda, pelo mesmo
+-- motivo, antes de virar o próximo incidente.
+--
+-- ── O que muda de verdade ──────────────────────────────────────────────────
+-- Nada no que cada política DECIDE. O que muda é onde a decisão é tomada: o
+-- que não depende da linha sai de dentro do laço. As políticas são geradas —
+-- `scaffold_table`, `scaffold_refresh_policies`, `scaffold_distributable`,
+-- `masked_view_refresh` — então a correção mora nos geradores, e o bloco final
+-- os re-executa para todas as tabelas do registro.
+-- ---------------------------------------------------------------------------
+
+-- ---------------------------------------------------------------------------
+-- 1. A pergunta barata: existe ALGUMA tupla deste tipo neste tenant?
+--    Não recebe id de linha de propósito — é o que a deixa sair do laço.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION app.grants_exist(p_type text, p_relations text[])
+  RETURNS boolean
+  LANGUAGE sql STABLE SECURITY DEFINER
+  SET search_path TO ''
+  AS $$
+  SELECT EXISTS (
+    SELECT 1 FROM app.resource_grants g
+     WHERE g.tenant_id = app.current_tenant_id()
+       AND g.resource_type = p_type
+       AND g.relation = ANY (p_relations)
+  );
+$$;
+
+REVOKE ALL ON FUNCTION app.grants_exist(text, text[]) FROM PUBLIC;
+GRANT ALL ON FUNCTION app.grants_exist(text, text[]) TO authenticated;
+GRANT ALL ON FUNCTION app.grants_exist(text, text[]) TO service_role;
+
+COMMENT ON FUNCTION app.grants_exist(text, text[]) IS
+  'Este tenant tem alguma tupla destas relações para este tipo de recurso (#016)? Não recebe id de linha porque a pergunta não é sobre a linha — é o que permite ao planejador promovê-la a InitPlan e tirar a regra cara de dentro do laço da RLS.';
+
+-- ---------------------------------------------------------------------------
+-- 2. A mesma saída antecipada DENTRO da função, para quem a chama direto
+--    (RPCs, views, `excluded_in_my_units`) e não passa por política nenhuma.
+--    Corpo idêntico ao da 000 depois da guarda.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION app.available_in_my_units(p_type text, p_id uuid)
+  RETURNS boolean
+  LANGUAGE sql STABLE SECURITY DEFINER
+  SET search_path TO ''
+  AS $$
+  -- Sem nenhuma tupla deste tipo no tenant não há o que resolver: a derivação
+  -- está no cabeçalho da 016 e termina em `true` para toda linha. Um CASE e não
+  -- um OR porque o ramo do CASE é avaliado sob demanda de forma garantida — as
+  -- CTEs abaixo nem chegam a ser montadas. A guarda é uma sondagem de índice no
+  -- prefixo (tenant_id, resource_type) da PK de resource_grants.
+  SELECT CASE
+    WHEN NOT app.grants_exist(p_type, ARRAY['available_in', 'unavailable_in']) THEN true
+    ELSE (
+      WITH me AS (
+        SELECT app.current_tenant_id() AS tenant_id,
+               auth.uid()              AS uid,
+               nullif(app.current_unit_id(), '00000000-0000-0000-0000-000000000000'::uuid) AS focus
+      ),
+      tup AS (
+        SELECT g.relation, g.subject_type, g.subject_id
+          FROM app.resource_grants g, me
+         WHERE g.tenant_id = me.tenant_id AND g.resource_type = p_type AND g.resource_id = p_id
+           AND g.relation IN ('available_in', 'unavailable_in')
+      ),
+      -- me, or a role of mine: outside the tree, so it simply decides
+      direct AS (
+        SELECT t.relation FROM tup t, me
+         WHERE (t.subject_type = 'user' AND t.subject_id = me.uid)
+            OR (t.subject_type = 'role' AND t.subject_id IN (
+                  SELECT m.role_id FROM app.memberships m
+                   WHERE m.tenant_id = me.tenant_id AND m.user_id = me.uid AND m.active
+                  UNION
+                  SELECT mu.role_override_id FROM app.membership_units mu
+                   WHERE mu.tenant_id = me.tenant_id AND mu.user_id = me.uid AND mu.role_override_id IS NOT NULL))
+      ),
+      mine AS (
+        SELECT a.unit_id FROM app.user_unit_access a, me
+         WHERE a.tenant_id = me.tenant_id AND a.user_id = me.uid
+           AND (me.focus IS NULL OR a.unit_id = me.focus)
+      ),
+      verdicts AS (
+        SELECT app.unit_release_verdict(p_type, p_id, mine.unit_id) AS v FROM mine
+      )
+      SELECT NOT EXISTS (SELECT 1 FROM direct WHERE relation = 'unavailable_in')
+         AND (
+              EXISTS (SELECT 1 FROM direct WHERE relation = 'available_in')
+           OR EXISTS (SELECT 1 FROM verdicts WHERE v = 'allow')
+           OR (NOT EXISTS (SELECT 1 FROM tup WHERE relation = 'available_in')
+               AND (EXISTS (SELECT 1 FROM verdicts WHERE v = 'none') OR NOT EXISTS (SELECT 1 FROM mine)))
+         )
+    )
+  END;
+$$;
+
+-- ---------------------------------------------------------------------------
+-- 3. Como uma checagem de permissão é RENDERIZADA num predicado de varredura.
+--    Um lugar só, porque quatro geradores a escrevem.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION app.scaffold_perm_sql(p_perm text, p_scope text DEFAULT NULL::text)
+  RETURNS text
+  LANGUAGE sql IMMUTABLE
+  SET search_path TO ''
+  AS $$
+  -- `unit` = a coluna é NOT NULL, então o ramo do NULL é código morto e a forma
+  -- curta é a honesta. Fora disso, o CASE separa o caso que não depende da
+  -- linha (InitPlan, uma vez) do que depende (SubPlan, como sempre foi).
+  SELECT CASE WHEN p_scope = 'unit'
+    THEN format('(select app.has_permission(%L, unit_id))', p_perm)
+    ELSE format('(CASE WHEN unit_id IS NULL'
+             || ' THEN (select app.has_permission(%L, NULL::uuid))'
+             || ' ELSE (select app.has_permission(%L, unit_id)) END)', p_perm, p_perm)
+  END;
+$$;
+
+-- O `p_scope` novo faz desta uma função NOVA — a de um argumento continua
+-- existindo —, e função nova nasce com EXECUTE para PUBLIC, que inclui `anon`.
+-- Nada em `app` é chamável de fora; é o que a asserção N15c da postura grada.
+REVOKE ALL ON FUNCTION app.scaffold_perm_sql(text, text) FROM PUBLIC;
+GRANT ALL ON FUNCTION app.scaffold_perm_sql(text, text) TO service_role;
+
+COMMENT ON FUNCTION app.scaffold_perm_sql(text, text) IS
+  'Renderiza a checagem de permissão de um predicado de varredura (#016). O ramo `unit_id IS NULL` não menciona coluna nenhuma e por isso vira InitPlan — é o que impede uma pergunta de resposta constante de ser feita uma vez por linha.';
+
+-- ---------------------------------------------------------------------------
+-- 4. O predicado de escopo compartilhado por select/update/delete.
+--    Mesmas decisões da 000; o que muda é onde elas são avaliadas.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION app.scaffold_scope_sql(p_resource_type text, p_plugin text, p_scope text DEFAULT NULL::text)
+  RETURNS text
+  LANGUAGE sql IMMUTABLE
+  SET search_path TO ''
+  AS $$
+  SELECT 'tenant_id = (select app.current_tenant_id())'
+      || CASE WHEN p_scope = 'unit'
+              THEN ' AND (select app.has_unit(unit_id))'
+              ELSE ' AND (unit_id IS NULL OR (select app.has_unit(unit_id)))' END
+      || format(
+           ' AND (NOT (select app.owner_scoped(%L))'
+        ||      ' OR owner_id IS NULL OR owner_id = (select auth.uid())'
+        --   A guarda barata na frente da cara: sem tupla `shared_with` deste
+        --   tipo no tenant, `has_grant` só pode responder false, e agora
+        --   responde isso uma vez em vez de uma vez por linha.
+        ||      ' OR ((select app.grants_exist(%L, ARRAY[''shared_with'']))'
+        ||          ' AND (select app.has_grant(%L, id, ARRAY[''shared_with''])))'
+        ||      ' OR %s)',
+           p_resource_type, p_resource_type, p_resource_type,
+           app.scaffold_perm_sql(p_plugin || '.read_all', p_scope));
+$$;
+
+-- ---------------------------------------------------------------------------
+-- 5. Os geradores de política. Idênticos aos da 000 fora a renderização.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION app.scaffold_refresh_policies(p_table text) RETURNS void
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+DECLARE
+  v_schema text := split_part(replace(p_table, '"', ''), '.', 1);
+  v_name   text := split_part(replace(p_table, '"', ''), '.', 2);
+  v_q      text := format('%I.%I', split_part(replace(p_table, '"', ''), '.', 1), split_part(replace(p_table, '"', ''), '.', 2));
+  r        app.scaffold_registry%ROWTYPE;
+  v_scope  text;
+  v_class  text;
+BEGIN
+  SELECT * INTO r FROM app.scaffold_registry WHERE table_schema = v_schema AND table_name = v_name;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'scaffold_refresh_policies: %.% is not in the scaffold registry', v_schema, v_name USING ERRCODE = 'P0002';
+  END IF;
+
+  -- The `unit` rendering drops the `unit_id IS NULL OR` branch, which is only
+  -- sound when the column really is NOT NULL. Declaring a table `unit` while its
+  -- writers still produce NULLs is exactly the state this file leaves most tables
+  -- in — so the optimisation follows the CONSTRAINT, never the label. Getting
+  -- this wrong hid every unit-less financial movement and took
+  -- v_financial_customer_credit to 0.00.
+  SELECT CASE WHEN c.is_nullable = 'NO' THEN 'unit' ELSE NULL END INTO v_class
+    FROM information_schema.columns c
+   WHERE c.table_schema = v_schema AND c.table_name = v_name AND c.column_name = 'unit_id';
+  v_scope := app.scaffold_scope_sql(r.resource_type, r.plugin, v_class);
+
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_select', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR SELECT TO authenticated USING (%s AND %s)',
+                 v_name || '_authz_select', v_q, v_scope, app.scaffold_perm_sql(r.plugin || '.read', v_class));
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_update', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR UPDATE TO authenticated USING (%s AND %s) WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (unit_id IS NULL OR (select app.has_unit(unit_id))) AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_update', v_q, v_scope, app.scaffold_perm_sql(r.plugin || '.edit', v_class), r.plugin || '.edit');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_delete', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR DELETE TO authenticated USING (%s AND %s)',
+                 v_name || '_authz_delete', v_q, v_scope, app.scaffold_perm_sql(r.plugin || '.delete', v_class));
+END $$;
+
+CREATE OR REPLACE FUNCTION app.scaffold_distributable(p_table regclass, p_resource_type text DEFAULT NULL::text, p_key_column text DEFAULT 'id'::text, p_unit_escape boolean DEFAULT true, p_enabled boolean DEFAULT true) RETURNS void
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+DECLARE
+  v_schema text; v_name text; v_q text; v_policy text;
+  r app.scaffold_registry%ROWTYPE; v_rt text;
+BEGIN
+  SELECT n.nspname, c.relname INTO v_schema, v_name
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = p_table;
+  v_q := format('%I.%I', v_schema, v_name);
+  v_policy := v_name || '_available_in';
+
+  SELECT * INTO r FROM app.scaffold_registry WHERE table_schema = v_schema AND table_name = v_name;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'scaffold_distributable: %.% is not scaffolded', v_schema, v_name USING ERRCODE = 'P0002';
+  END IF;
+  v_rt := coalesce(p_resource_type, r.resource_type);
+
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_policy, v_q);
+
+  IF p_enabled THEN
+    IF NOT EXISTS (SELECT 1 FROM information_schema.columns
+                    WHERE table_schema = v_schema AND table_name = v_name AND column_name = p_key_column) THEN
+      RAISE EXCEPTION 'scaffold_distributable: %.% has no column %', v_schema, v_name, p_key_column;
+    END IF;
+    -- RESTRICTIVE: permissive policies OR together, so a release rule that is
+    -- meant to REMOVE rows has to AND with the scaffold's select.
+    --
+    -- A guarda vem PRIMEIRO e sem coluna nenhuma: é o que a torna InitPlan.
+    -- Quando o tenant não distribui este tipo de recurso — o caso de todo
+    -- tenant hoje — a regra cara não é chamada nem uma vez.
+    EXECUTE format(
+      'CREATE POLICY %I ON %s AS RESTRICTIVE FOR SELECT TO authenticated USING (NOT (select app.grants_exist(%L, ARRAY[''available_in'', ''unavailable_in''])) OR %s(select app.available_in_my_units(%L, %I)))',
+      v_policy, v_q, v_rt,
+      CASE WHEN p_unit_escape THEN 'unit_id IS NOT NULL OR ' ELSE '' END,
+      v_rt, p_key_column);
+  END IF;
+
+  UPDATE app.scaffold_registry
+     SET distributable = p_enabled,
+         dist_resource_type = CASE WHEN p_enabled THEN v_rt END,
+         dist_key_column    = CASE WHEN p_enabled THEN p_key_column END,
+         dist_unit_escape   = CASE WHEN p_enabled THEN p_unit_escape END
+   WHERE table_schema = v_schema AND table_name = v_name;
+END $$;
+
+-- O gerador de tabela nova: a mesma renderização, para que uma tabela criada
+-- depois desta migration já nasça com a forma rápida.
+CREATE OR REPLACE FUNCTION app.scaffold_table(p_table regclass, p_resource_type text, p_plugin text, p_owner_scoping boolean DEFAULT true, p_mode text DEFAULT 'enforce'::text) RETURNS void
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+DECLARE
+  v_schema text;
+  v_name   text;
+  v_q      text;   -- quoted qualified name
+  v_prev   text[] := '{}';
+  v_rows   bigint;
+  r        record;
+  v_scope  text;   -- the row-scope predicate shared by every policy
+BEGIN
+  IF p_mode NOT IN ('shadow', 'enforce') THEN
+    RAISE EXCEPTION 'scaffold_table: mode must be shadow|enforce';
+  END IF;
+  SELECT n.nspname, c.relname INTO v_schema, v_name
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = p_table;
+  v_q := format('%I.%I', v_schema, v_name);
+
+  -- ── columns
+  IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = v_schema AND table_name = v_name AND column_name = 'id') THEN
+    RAISE EXCEPTION 'scaffold_table: % has no id column', v_q;
+  END IF;
+  EXECUTE format('SELECT count(*) FROM %s', v_q) INTO v_rows;
+  IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = v_schema AND table_name = v_name AND column_name = 'tenant_id') THEN
+    EXECUTE format('ALTER TABLE %s ADD COLUMN tenant_id uuid REFERENCES public.tenants(id) ON DELETE CASCADE', v_q);
+    IF v_rows = 0 THEN EXECUTE format('ALTER TABLE %s ALTER COLUMN tenant_id SET NOT NULL', v_q); END IF;
+  END IF;
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS unit_id uuid', v_q);
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS owner_id uuid', v_q);
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS created_at timestamptz NOT NULL DEFAULT now()', v_q);
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS updated_at timestamptz NOT NULL DEFAULT now()', v_q);
+
+  -- ── unique(tenant_id, id) — enables composite FKs from other tables
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_tenant_id_id_key') THEN
+    EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I UNIQUE (tenant_id, id)', v_q, v_name || '_tenant_id_id_key');
+  END IF;
+  -- ── composite FKs: unit within tenant, owner a member of the tenant
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_unit_fk') THEN
+    EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I FOREIGN KEY (tenant_id, unit_id) REFERENCES app.units(tenant_id, id) ON DELETE SET NULL', v_q, v_name || '_unit_fk');
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_owner_fk') THEN
+    EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I FOREIGN KEY (tenant_id, owner_id) REFERENCES app.memberships(tenant_id, user_id) ON DELETE SET NULL', v_q, v_name || '_owner_fk');
+  END IF;
+
+  -- ── tenant-first indexes
+  EXECUTE format('CREATE INDEX IF NOT EXISTS %I ON %s (tenant_id, unit_id)', v_name || '_tenant_unit_idx', v_q);
+  EXECUTE format('CREATE INDEX IF NOT EXISTS %I ON %s (tenant_id, owner_id) WHERE owner_id IS NOT NULL', v_name || '_tenant_owner_idx', v_q);
+
+  -- ── updated_at
+  EXECUTE format('DROP TRIGGER IF EXISTS %I ON %s', v_name || '_updated_at', v_q);
+  EXECUTE format('CREATE TRIGGER %I BEFORE UPDATE ON %s FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at()', v_name || '_updated_at', v_q);
+
+  -- ── RLS
+  EXECUTE format('ALTER TABLE %s ENABLE ROW LEVEL SECURITY', v_q);
+  EXECUTE format('ALTER TABLE %s FORCE ROW LEVEL SECURITY', v_q);
+  IF p_mode = 'enforce' THEN
+    FOR r IN SELECT policyname FROM pg_policies WHERE schemaname = v_schema AND tablename = v_name
+             AND policyname NOT IN (v_name || '_authz_select', v_name || '_authz_insert', v_name || '_authz_update', v_name || '_authz_delete') LOOP
+      v_prev := v_prev || r.policyname;
+      EXECUTE format('DROP POLICY IF EXISTS %I ON %s', r.policyname, v_q);
+    END LOOP;
+  END IF;
+
+  v_scope := app.scaffold_scope_sql(p_resource_type, p_plugin);
+
+  -- SELECT/UPDATE/DELETE varrem, então rendem pelo `scaffold_perm_sql`. O
+  -- WITH CHECK do INSERT não varre — ele julga a linha que está sendo escrita,
+  -- uma de cada vez — e por isso fica como estava.
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_select', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR SELECT TO authenticated USING (%s AND %s)',
+                 v_name || '_authz_select', v_q, v_scope, app.scaffold_perm_sql(p_plugin || '.read'));
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_insert', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR INSERT TO authenticated WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (unit_id IS NULL OR (select app.has_unit(unit_id))) AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_insert', v_q, p_plugin || '.create');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_update', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR UPDATE TO authenticated USING (%s AND %s) WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (unit_id IS NULL OR (select app.has_unit(unit_id))) AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_update', v_q, v_scope, app.scaffold_perm_sql(p_plugin || '.edit'), p_plugin || '.edit');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_delete', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR DELETE TO authenticated USING (%s AND %s)',
+                 v_name || '_authz_delete', v_q, v_scope, app.scaffold_perm_sql(p_plugin || '.delete'));
+
+  -- scope defaults on REGISTRATION, so a table cannot exist in the registry
+  -- unclassified. A plugin's tables are scaffolded after the core chain has run,
+  -- so 136's DO block could never have reached them — they arrive here instead,
+  -- declared `unit_optional` until the plugin says otherwise.
+  INSERT INTO app.scaffold_registry (table_schema, table_name, resource_type, plugin, owner_scoping, mode, previous_policies, scope)
+  VALUES (v_schema, v_name, p_resource_type, p_plugin, p_owner_scoping, p_mode, v_prev, 'unit_optional')
+  ON CONFLICT (table_schema, table_name) DO UPDATE
+    SET resource_type = EXCLUDED.resource_type, plugin = EXCLUDED.plugin, owner_scoping = EXCLUDED.owner_scoping,
+        scope = coalesce(app.scaffold_registry.scope, EXCLUDED.scope),
+        mode = EXCLUDED.mode, applied_at = now(),
+        previous_policies = CASE WHEN EXCLUDED.mode = 'enforce' AND app.scaffold_registry.mode = 'shadow'
+                                 THEN app.scaffold_registry.previous_policies || EXCLUDED.previous_policies
+                                 ELSE EXCLUDED.previous_policies END;
+END $$;
+
+-- A view mascarada renderiza O MESMO predicado, com o mesmo `has_permission`
+-- por linha. Herda a correção pela mesma porta.
+CREATE OR REPLACE FUNCTION app.masked_view_refresh(p_table regclass, p_context text, p_reference text) RETURNS void
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+DECLARE
+  v_schema    text;
+  v_name      text;
+  v_view      text;
+  r           app.scaffold_registry%ROWTYPE;
+  v_cols      text;
+  v_class     text;
+  v_structural constant text[] := ARRAY['id','tenant_id','unit_id','owner_id','created_at','updated_at'];
+BEGIN
+  SELECT n.nspname, c.relname INTO v_schema, v_name
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = p_table;
+
+  SELECT * INTO r FROM app.scaffold_registry WHERE table_schema = v_schema AND table_name = v_name;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'masked_view_refresh: %.% is not scaffolded — the view renders the scaffold''s own predicate', v_schema, v_name
+      USING ERRCODE = 'P0002';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM public.field_rule_contexts WHERE key = p_context) THEN
+    RAISE EXCEPTION 'masked_view_refresh: unknown field-rule context %', p_context USING ERRCODE = '23503';
+  END IF;
+
+  v_view := 'v_' || v_name;
+
+  SELECT string_agg(
+           CASE WHEN c.column_name = ANY (v_structural)
+                THEN format('%I', c.column_name)
+                -- `@>` and not `= ANY (…)`: a parenthesised scalar subquery is
+                -- parsed as ANY's SUBQUERY form, which compares against rows and
+                -- chokes on a text[]. Containment takes the array directly and
+                -- still plans as a once-per-statement InitPlan.
+                ELSE format('CASE WHEN NOT ((select app.hidden_fields(%L, %L)) @> ARRAY[%L::text]) THEN %I END AS %I',
+                            p_context, p_reference, c.column_name, c.column_name, c.column_name)
+           END, E',\n       ' ORDER BY c.ordinal_position)
+    INTO v_cols
+    FROM information_schema.columns c
+   WHERE c.table_schema = v_schema AND c.table_name = v_name;
+
+  SELECT CASE WHEN c.is_nullable = 'NO' THEN 'unit' ELSE NULL END INTO v_class
+    FROM information_schema.columns c
+   WHERE c.table_schema = v_schema AND c.table_name = v_name AND c.column_name = 'unit_id';
+
+  EXECUTE format('DROP VIEW IF EXISTS %I.%I', v_schema, v_view);
+  -- Owner rights on purpose (see the header): the predicate below IS the
+  -- scaffold's, rendered from the same function the policies render from.
+  EXECUTE format(
+    'CREATE VIEW %I.%I AS SELECT %s FROM %I.%I WHERE %s AND %s',
+    v_schema, v_view, v_cols, v_schema, v_name,
+    app.scaffold_scope_sql(r.resource_type, r.plugin, v_class),
+    app.scaffold_perm_sql(r.plugin || '.read', v_class));
+
+  EXECUTE format('REVOKE ALL ON %I.%I FROM public, anon', v_schema, v_view);
+  EXECUTE format('GRANT SELECT ON %I.%I TO authenticated, service_role', v_schema, v_view);
+  EXECUTE format(
+    'COMMENT ON VIEW %I.%I IS %L',
+    v_schema, v_view,
+    format('Masked read of %I.%I (#221): every non-structural column reads NULL when field_rules hides it for the caller''s role and unit. Owner rights with the scaffold''s own row predicate — regenerate with app.masked_view_refresh(''%I.%I'', %L, %L), never edit by hand.',
+           v_schema, v_name, v_schema, v_name, p_context, p_reference));
+
+  INSERT INTO app.masked_views (table_schema, table_name, view_name, context, reference)
+  VALUES (v_schema, v_name, v_view, p_context, p_reference)
+  ON CONFLICT (table_schema, table_name) DO UPDATE
+    SET view_name = EXCLUDED.view_name, context = EXCLUDED.context,
+        reference = EXCLUDED.reference, applied_at = now();
+END $$;
+
+-- ---------------------------------------------------------------------------
+-- 6. Reescrever o que já está no banco. Um gerador corrigido não corrige nada
+--    sozinho: o texto das políticas existentes foi assado quando elas foram
+--    criadas. Idempotente — cada gerador derruba e recria a sua própria
+--    política a partir do registro.
+-- ---------------------------------------------------------------------------
+DO $$
+DECLARE r record; v_n int := 0;
+BEGIN
+  FOR r IN SELECT table_schema, table_name FROM app.scaffold_registry ORDER BY 1, 2 LOOP
+    -- `public.items` e `public.item_associations` ficam de fora, e é a única
+    -- exceção nominal desta migration.
+    --
+    -- A permissão delas NÃO é constante por tabela: a linha de uma fatura pede
+    -- `financial.read`, a de uma remessa `inventory.read`, a de um pedido
+    -- `orders.read`, e quem decide é a `parent_kind` — coluna gerada, uma por
+    -- LINHA. O baseline escreveu essas quatro políticas à mão com esse CASE
+    -- dentro, e o renderizador genérico só sabe emitir um `plugin.ação` fixo:
+    -- regerá-las aqui achataria o despacho e tornaria uma linha de fatura
+    -- legível com `orders.read` sozinho. É fronteira de permissão, não estilo,
+    -- e a suíte 110_commercial_line existe para não deixar isso passar.
+    --
+    -- O custo de ficarem fora é a checagem por linha que a 016 tira das outras;
+    -- é um custo conhecido e escrito, e não foi delas que veio o teto de 8s.
+    -- Expressá-las no registro (uma coluna de despacho por plugin) é o
+    -- trabalho que fecha esta exceção.
+    CONTINUE WHEN r.table_schema = 'public' AND r.table_name IN ('items', 'item_associations');
+    -- Uma linha do registro pode apontar para uma tabela que já não existe
+    -- (plugin desinstalado). Pular é a resposta certa: não é papel desta
+    -- migration ter opinião sobre isso.
+    CONTINUE WHEN to_regclass(format('%I.%I', r.table_schema, r.table_name)) IS NULL;
+    -- E pode apontar para uma tabela que não tem as colunas do andaime: 16
+    -- linhas de plugin entraram no registro por INSERT direto, sem passar pelo
+    -- `scaffold_table` que as cria, e ficaram sem `unit_id`, sem `owner_id` ou
+    -- (uma) sem `id`. O gerador NUNCA conseguiu rodar nelas — o predicado que
+    -- ele escreve nomeia as quatro — e as políticas que elas têm foram escritas
+    -- à mão. Pular preserva o que já valia; tentar derrubaria a migration
+    -- inteira por causa de uma tabela que ela não governa.
+    --
+    -- É um desalinhamento real entre o registro e o esquema, e ele continua
+    -- depois desta migration. Fica o NOTICE; consertar é assunto do plugin.
+    CONTINUE WHEN EXISTS (
+      SELECT 1 FROM unnest(ARRAY['id', 'tenant_id', 'unit_id', 'owner_id']) col
+       WHERE NOT EXISTS (
+         SELECT 1 FROM information_schema.columns c
+          WHERE c.table_schema = r.table_schema AND c.table_name = r.table_name
+            AND c.column_name = col));
+    PERFORM app.scaffold_refresh_policies(r.table_schema || '.' || r.table_name);
+    v_n := v_n + 1;
+  END LOOP;
+  RAISE NOTICE '016: % tabela(s) com o predicado de varredura regerado', v_n;
+
+  v_n := 0;
+  FOR r IN SELECT table_schema, table_name, dist_resource_type, dist_key_column, dist_unit_escape
+             FROM app.scaffold_registry WHERE distributable ORDER BY 1, 2 LOOP
+    CONTINUE WHEN to_regclass(format('%I.%I', r.table_schema, r.table_name)) IS NULL;
+    PERFORM app.scaffold_distributable(
+      to_regclass(format('%I.%I', r.table_schema, r.table_name)),
+      r.dist_resource_type, coalesce(r.dist_key_column, 'id'), coalesce(r.dist_unit_escape, true), true);
+    v_n := v_n + 1;
+  END LOOP;
+  RAISE NOTICE '016: % política(s) de distribuição regerada(s)', v_n;
+
+  v_n := 0;
+  FOR r IN SELECT table_schema, table_name, context, reference FROM app.masked_views ORDER BY 1, 2 LOOP
+    CONTINUE WHEN to_regclass(format('%I.%I', r.table_schema, r.table_name)) IS NULL;
+    PERFORM app.masked_view_refresh(
+      to_regclass(format('%I.%I', r.table_schema, r.table_name)), r.context, r.reference);
+    v_n := v_n + 1;
+  END LOOP;
+  RAISE NOTICE '016: % view(s) mascarada(s) regerada(s)', v_n;
+END $$;