@fayz-ai/db 0.14.0 → 0.16.0

package/migrations/079_quem_aparece_na_agenda_e_quem_atende.sql

@@ -0,0 +1,210 @@
+-- Quem aparece na agenda é quem atende.
+--
+-- A agenda de uma unidade mostrava gente demais, e a maior parte do excesso
+-- não era profissional. Medido em 20/09/2026, agenda do Millenium:
+--
+--     23  funcionários administrativos
+--     15  profissionais          (o V1 diz 11)
+--      1  cliente
+--     ──
+--     38  colunas, onde deveriam ser 11
+--
+-- ── A causa ─────────────────────────────────────────────────────────────────
+--
+-- `public.people.is_bookable` tem `DEFAULT true`, e `migration.upsert_person`
+-- nunca o define. Então TODA pessoa que o porte escreve nasce agendável —
+-- inclusive os 119.521 clientes, que só não aparecem porque a agenda filtra
+-- por `kind = 'staff'`.
+--
+-- O V1 distingue: quem atende cliente é `professionals`; `employees` é
+-- administrativo e nunca vira coluna na agenda de lá. A informação existia na
+-- origem e não atravessava.
+--
+-- ── Declarado, não derivado ─────────────────────────────────────────────────
+--
+-- O writer já recebe `role` em `writer_args`, e seria fácil escrever
+-- `is_bookable := (v_role = 'professional')` aqui dentro. Não é o que esta
+-- migration faz.
+--
+-- A regra vai para `writer_args.bookable`, por tabela de origem, porque ela é
+-- uma decisão do POOL e não do motor: um cliente onde a recepção também atende
+-- precisa poder dizer isso sem que alguém reescreva o writer. Ausente, o
+-- destino decide — o comportamento de antes, para todo pool que já roda.
+--
+-- Idempotente.
+
+CREATE OR REPLACE FUNCTION migration.upsert_person(p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb)
+ RETURNS jsonb
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE
+  v_role text := coalesce(p_args ->> 'role', 'customer');
+  v_doc text := public.people_normalize_document(p_row ->> 'document_number');
+  v_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_origin jsonb;
+  v_existing_tenant uuid;
+  v_tombstone uuid;
+  v_candidates uuid[];
+  v_n integer;
+  v_survivor uuid;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL OR nullif(btrim(coalesce(p_row ->> 'name', '')), '') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a person needs an id and a name');
+  END IF;
+  IF v_role NOT IN ('customer', 'professional', 'employee', 'contact', 'supplier', 'lead') THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', format('unknown person role %s', v_role));
+  END IF;
+  v_origin := coalesce(v_meta -> 'migration', '{}'::jsonb) - 'merged_from';
+
+  SELECT tenant_id, merged_into_id INTO v_existing_tenant, v_tombstone FROM public.people WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('person %s already exists in another tenant', p_id));
+  END IF;
+  IF v_tombstone IS NOT NULL THEN
+    -- the row was merged in V2 after it landed: the human's decision stands, the source now maps to the survivor
+    PERFORM migration._ensure_role(p_tenant, v_tombstone, v_role);
+    RETURN jsonb_build_object('status', 'migrated', 'target_id', v_tombstone, 'reason', 'merged', 'merged', true);
+  END IF;
+
+  IF v_existing_tenant IS NOT NULL THEN
+    -- the same source row again (delta): mapped columns override, the rest stays
+    UPDATE public.people SET
+      name = p_row ->> 'name',
+      email = CASE WHEN p_row ? 'email' THEN p_row ->> 'email' ELSE email END,
+      phone = CASE WHEN p_row ? 'phone' THEN p_row ->> 'phone' ELSE phone END,
+      document_number = CASE WHEN p_row ? 'document_number' THEN v_doc ELSE document_number END,
+      avatar_url = CASE WHEN p_row ? 'avatar_url' THEN p_row ->> 'avatar_url' ELSE avatar_url END,
+      date_of_birth = CASE WHEN p_row ? 'date_of_birth' THEN (p_row ->> 'date_of_birth')::date ELSE date_of_birth END,
+      address = CASE WHEN p_row ? 'address' THEN p_row ->> 'address' ELSE address END,
+      city = CASE WHEN p_row ? 'city' THEN p_row ->> 'city' ELSE city END,
+      state = CASE WHEN p_row ? 'state' THEN p_row ->> 'state' ELSE state END,
+      country = CASE WHEN p_row ? 'country' THEN p_row ->> 'country' ELSE country END,
+      postal_code = CASE WHEN p_row ? 'postal_code' THEN p_row ->> 'postal_code' ELSE postal_code END,
+      notes = CASE WHEN p_row ? 'notes' THEN p_row ->> 'notes' ELSE notes END,
+      is_active = CASE WHEN p_row ? 'is_active' THEN coalesce((p_row ->> 'is_active')::boolean, true) ELSE is_active END,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+    PERFORM migration._ensure_role(p_tenant, p_id, v_role);
+    PERFORM migration._set_unit('public.people', p_id, (p_row ->> 'unit_id')::uuid);
+    IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.people', p_id, jsonb_build_object('reason', 'updated')); END IF;
+    RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'updated');
+  END IF;
+
+  IF v_doc IS NOT NULL THEN
+    SELECT array_agg(id) INTO v_candidates FROM public.people
+     WHERE tenant_id = p_tenant AND document_number = v_doc AND merged_into_id IS NULL;
+  ELSIF nullif(btrim(coalesce(p_row ->> 'email', '')), '') IS NOT NULL AND nullif(public.fayz_digits(p_row ->> 'phone'), '') IS NOT NULL THEN
+    SELECT array_agg(id) INTO v_candidates FROM public.people
+     WHERE tenant_id = p_tenant AND merged_into_id IS NULL AND lower(email) = lower(p_row ->> 'email')
+       AND public.fayz_digits(phone) = public.fayz_digits(p_row ->> 'phone');
+  END IF;
+  v_n := coalesce(array_length(v_candidates, 1), 0);
+
+  IF v_doc IS NOT NULL AND v_n >= 2 THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'identity',
+      'reason', format('ambiguous document: %s existing people share document %s', v_n, v_doc), 'candidates', to_jsonb(v_candidates));
+  END IF;
+  IF v_doc IS NULL AND v_n >= 1 THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'identity',
+      'reason', format('no document: %s existing person(s) share the same email and phone — merge only by exact document', v_n), 'candidates', to_jsonb(v_candidates));
+  END IF;
+
+  IF v_doc IS NOT NULL AND v_n = 1 THEN
+    v_survivor := v_candidates[1];
+    UPDATE public.people SET
+      email = coalesce(email, p_row ->> 'email'),
+      phone = coalesce(phone, p_row ->> 'phone'),
+      avatar_url = coalesce(avatar_url, p_row ->> 'avatar_url'),
+      date_of_birth = coalesce(date_of_birth, (p_row ->> 'date_of_birth')::date),
+      address = coalesce(address, p_row ->> 'address'),
+      city = coalesce(city, p_row ->> 'city'),
+      state = coalesce(state, p_row ->> 'state'),
+      country = coalesce(country, p_row ->> 'country'),
+      postal_code = coalesce(postal_code, p_row ->> 'postal_code'),
+      notes = coalesce(notes, p_row ->> 'notes'),
+      metadata = migration._merge_meta(metadata,
+        (v_meta - 'migration') || jsonb_build_object('migration', jsonb_build_object('merged_from', jsonb_build_array(v_origin))))
+    WHERE id = v_survivor;
+    PERFORM migration._ensure_role(p_tenant, v_survivor, v_role);
+    IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.people', v_survivor, jsonb_build_object('reason', 'merged', 'origin', v_origin)); END IF;
+    RETURN jsonb_build_object('status', 'migrated', 'target_id', v_survivor, 'reason', 'merged', 'merged', true);
+  END IF;
+
+  -- kind is written for compatibility only; the role row below is the truth
+  -- (fayz.people_kind_sync = on keeps the kind→role trigger quiet meanwhile)
+  PERFORM set_config('fayz.people_kind_sync', 'on', true);
+  -- `is_bookable` decide quem vira COLUNA na agenda, e a coluna do destino tem
+  -- DEFAULT true — então, sem isto, toda pessoa migrada nasce agendável. O
+  -- papel da origem é quem sabe: no V1 quem atende cliente é `professionals`;
+  -- `employees` é administrativo e nunca aparece na agenda de lá.
+  --
+  -- É DECLARADO em `writer_args.bookable`, por tabela de origem, e não
+  -- derivado do papel aqui dentro: um pool onde a recepção também atende deve
+  -- poder dizer isso sem reescrever o writer. Ausente, o destino decide — que
+  -- é o comportamento de antes.
+  INSERT INTO public.people (id, tenant_id, kind, name, email, phone, document_number, avatar_url, date_of_birth,
+                             address, city, state, country, postal_code, notes, is_active, is_bookable, metadata)
+  VALUES (p_id, p_tenant, coalesce(public.person_role_to_kind(v_role), v_role), p_row ->> 'name', p_row ->> 'email', p_row ->> 'phone', v_doc,
+          p_row ->> 'avatar_url', (p_row ->> 'date_of_birth')::date, p_row ->> 'address', p_row ->> 'city', p_row ->> 'state',
+          coalesce(p_row ->> 'country', 'BR'), p_row ->> 'postal_code', p_row ->> 'notes',
+          coalesce((p_row ->> 'is_active')::boolean, true),
+          coalesce((p_args ->> 'bookable')::boolean, true), v_meta);
+  PERFORM set_config('fayz.people_kind_sync', 'off', true);
+  PERFORM migration._ensure_role(p_tenant, p_id, v_role);
+  PERFORM migration._set_unit('public.people', p_id, (p_row ->> 'unit_id')::uuid);
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.people', p_id, jsonb_build_object('reason', 'created')); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'created');
+END $function$
+
+;
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- A declaração, por tabela de origem
+-- ─────────────────────────────────────────────────────────────────────────────
+
+SET LOCAL migration.allowlist_unlock = 'on';
+
+UPDATE migration.allowlist
+   SET writer_args = coalesce(writer_args, '{}'::jsonb) || jsonb_build_object('bookable', true)
+ WHERE source_table = 'professionals';
+
+UPDATE migration.allowlist
+   SET writer_args = coalesce(writer_args, '{}'::jsonb) || jsonb_build_object('bookable', false)
+ WHERE source_table IN ('employees', 'clients', 'contacts');
+
+RESET migration.allowlist_unlock;
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- E o que já entrou
+-- ─────────────────────────────────────────────────────────────────────────────
+--
+-- Em LOTES, e não num UPDATE só: a junção com o ledger sobre 120 mil pessoas
+-- não termina dentro do `statement_timeout`, e um reparo que estoura desfaz a
+-- migration inteira junto. Cada volta é uma transação curta.
+--
+-- Só o que o PORTE escreveu — a condição exige linha no `migration.ledger`.
+-- Alguém que o V2 tenha marcado como agendável à mão fica como está: isso é
+-- decisão de quem usa o sistema, não do porte.
+
+DO $$
+DECLARE n integer;
+BEGIN
+  LOOP
+    UPDATE public.people p
+       SET is_bookable = false
+     WHERE p.ctid IN (
+       SELECT p2.ctid FROM public.people p2
+        JOIN migration.ledger l
+          ON l.target_id = p2.id
+         AND l.target_table = 'public.people'
+         AND l.source_table IN ('employees', 'clients', 'contacts')
+        WHERE p2.is_bookable
+        LIMIT 2000);
+    GET DIAGNOSTICS n = ROW_COUNT;
+    EXIT WHEN n = 0;
+  END LOOP;
+END $$;

package/migrations/080_o_contexto_da_requisicao_se_calcula_uma_vez.sql

@@ -0,0 +1,240 @@
+-- O contexto da requisição se calcula uma vez, não uma vez por linha.
+--
+-- Os painéis não carregavam: seis dos sete read models estouravam o
+-- `statement_timeout`. A causa não estava nos relatórios — estava embaixo
+-- deles.
+--
+-- ── A medição ───────────────────────────────────────────────────────────────
+--
+-- Contar UM MÊS de agenda, como `authenticated`, tenant Espaço Facial,
+-- 20/09/2026:
+--
+--     select count(*) from public.appointments
+--      where starts_at >= '2026-08-01' and starts_at < '2026-09-01'
+--     → 8.011 linhas em 21.947 ms
+--
+-- Note que é a TABELA CRUA, sem view nenhuma: **2,7 ms por linha**, tudo em
+-- RLS. E dentro dela:
+--
+--     app.has_unit(unidade)                  1,558 ms por chamada
+--     app.has_permission(chave, unidade)     1,002 ms
+--     app.owner_scoped(tipo)                 0,408 ms
+--
+-- `app.has_unit` sozinho chama `app.current_unit_id()` DUAS vezes,
+-- `app.unit_scoping_on()` e, dentro dela, `app.current_tenant_id()`. Cada uma
+-- com consulta própria — e todas respondem a MESMA COISA durante a requisição
+-- inteira: quem é o usuário, que tenant ele escolheu, que unidade está em
+-- foco, se a rede usa escopo por unidade.
+--
+-- Calcular isso por linha é o desperdício. Oito mil linhas × quatro perguntas
+-- cuja resposta não muda.
+--
+-- Vale dizer o que piorou: a migration 073, de hoje, ensinou
+-- `current_unit_id()` a ler o cabeçalho `x-fayz-unit` — e com isso acrescentou
+-- uma consulta a `app.user_unit_access` a cada chamada. O conserto estava
+-- certo; o preço dele é esta migration que paga.
+--
+-- ── A forma: invólucro, não reescrita ───────────────────────────────────────
+--
+-- As três funções mantêm o corpo EXATO que tinham, renomeadas para
+-- `app._*_raw()`. Por cima delas entra um invólucro que memoiza em um GUC
+-- transacional (`set_config(..., true)`).
+--
+-- Não reescrevi a lógica de propósito: ela decide quem vê o quê, e uma
+-- otimização não é hora de mexer em regra de acesso. O que muda é QUANTAS
+-- VEZES ela roda, não o que ela responde.
+--
+-- ── Por que memoizar é seguro aqui ──────────────────────────────────────────
+--
+-- O GUC é LOCAL: morre no fim da transação, e o PostgREST abre uma transação
+-- por requisição, com JWT e cabeçalhos fixos. Não há como a resposta mudar
+-- dentro do escopo do cache.
+--
+-- O sentinela `'-'` distingue "já calculei e deu NULL" de "ainda não
+-- calculei". Sem ele o caso NULL — que é o mais comum, "todas as unidades" —
+-- nunca seria memoizado, e o cache não serviria justamente para quem mais
+-- precisa.
+--
+-- Idempotente.
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 1. O corpo original, renomeado e intocado
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION app._current_tenant_id_raw()
+ RETURNS uuid
+ LANGUAGE plpgsql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE
+  v_uid    uuid := auth.uid();
+  v_jwt    jsonb := coalesce(auth.jwt(), '{}'::jsonb);
+  v_raw    text;
+  v_tenant uuid;
+  v_n      integer;
+BEGIN
+  -- ① a claim assinada, se existir. Inalterado desde 051.
+  IF jsonb_exists(v_jwt, 'tenant_id') THEN
+    v_raw := v_jwt ->> 'tenant_id';
+    -- Presença expressa intenção de estreitar; valor ilegível é nenhum tenant.
+    IF v_raw IS NULL OR v_raw !~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' THEN
+      RETURN NULL;
+    END IF;
+    v_tenant := v_raw::uuid;
+    IF v_uid IS NULL THEN
+      RETURN v_tenant;
+    END IF;
+    IF EXISTS (SELECT 1 FROM app.memberships m
+                WHERE m.tenant_id = v_tenant AND m.user_id = v_uid AND m.active) THEN
+      RETURN v_tenant;
+    END IF;
+    RETURN NULL;
+  END IF;
+
+  IF v_uid IS NULL THEN
+    RETURN NULL;
+  END IF;
+
+  -- ② o cabeçalho da requisição. A MESMA validação de filiação de ①: ele
+  -- escolhe entre as contas do usuário, não concede nenhuma. Sem sessão não há
+  -- o que validar, então este braço exige v_uid — que já está garantido acima.
+  v_tenant := app.requested_tenant();
+  IF v_tenant IS NOT NULL THEN
+    IF EXISTS (SELECT 1 FROM app.memberships m
+                WHERE m.tenant_id = v_tenant AND m.user_id = v_uid AND m.active) THEN
+      RETURN v_tenant;
+    END IF;
+    -- Cabeçalho apontando para conta que não é sua: nega, não recua. Recuar
+    -- para "sua única conta" transformaria um pedido explícito e errado numa
+    -- resposta silenciosa sobre outra conta.
+    RETURN NULL;
+  END IF;
+
+  -- ③ o recuo: conta única. Quem tem duas e não disse qual continua sem tenant,
+  -- que é a resposta correta — só que agora ela é evitável.
+  SELECT count(*), (array_agg(m.tenant_id))[1] INTO v_n, v_tenant
+    FROM app.memberships m WHERE m.user_id = v_uid AND m.active;
+  IF v_n = 1 THEN
+    RETURN v_tenant;
+  END IF;
+  RETURN NULL;
+END $function$
+
+;
+CREATE OR REPLACE FUNCTION app._current_unit_id_raw()
+ RETURNS uuid
+ LANGUAGE plpgsql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE
+  v_jwt jsonb := coalesce(auth.jwt(), '{}'::jsonb);
+  v_raw text;
+  v_unit uuid;
+  v_uid uuid;
+BEGIN
+  -- ① a claim assinada, quando existir. Inalterado.
+  IF jsonb_exists(v_jwt, 'unit_id') THEN
+    v_raw := v_jwt ->> 'unit_id';
+    IF v_raw IS NULL OR v_raw !~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' THEN
+      RETURN '00000000-0000-0000-0000-000000000000'::uuid;
+    END IF;
+    RETURN v_raw::uuid;
+  END IF;
+
+  -- ② o cabeçalho do app. Ele ESCOLHE entre as unidades que a pessoa já
+  -- alcança; não concede nenhuma.
+  v_unit := app.requested_unit();
+  IF v_unit IS NULL THEN
+    RETURN NULL;   -- "todas as unidades" — o seletor está em rede
+  END IF;
+
+  v_uid := auth.uid();
+  IF v_uid IS NULL THEN
+    RETURN '00000000-0000-0000-0000-000000000000'::uuid;
+  END IF;
+
+  IF EXISTS (SELECT 1 FROM app.user_unit_access a
+              WHERE a.tenant_id = app.current_tenant_id()
+                AND a.user_id = v_uid
+                AND a.unit_id = v_unit) THEN
+    RETURN v_unit;
+  END IF;
+
+  -- Pediu uma unidade que não é sua: nega. O sentinela não casa com unidade
+  -- nenhuma, então a tela vem vazia — que é a resposta certa, e muito melhor
+  -- que devolver a rede inteira.
+  RETURN '00000000-0000-0000-0000-000000000000'::uuid;
+END $function$
+
+;
+CREATE OR REPLACE FUNCTION app._unit_scoping_on_raw()
+ RETURNS boolean
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+  SELECT coalesce((SELECT t.unit_scoping_enabled FROM public.tenants t
+                    WHERE t.id = app.current_tenant_id()), false);
+$function$
+
+;
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 2. Os invólucros que memoizam
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION app.current_tenant_id()
+ RETURNS uuid
+ LANGUAGE plpgsql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE v_cache text := current_setting('app.ctx_tenant', true); v_out uuid;
+BEGIN
+  IF v_cache IS NOT NULL AND v_cache <> '' THEN
+    RETURN nullif(v_cache, '-')::uuid;
+  END IF;
+  v_out := app._current_tenant_id_raw();
+  PERFORM set_config('app.ctx_tenant', coalesce(v_out::text, '-'), true);
+  RETURN v_out;
+END $function$;
+
+CREATE OR REPLACE FUNCTION app.current_unit_id()
+ RETURNS uuid
+ LANGUAGE plpgsql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE v_cache text := current_setting('app.ctx_unit', true); v_out uuid;
+BEGIN
+  IF v_cache IS NOT NULL AND v_cache <> '' THEN
+    RETURN nullif(v_cache, '-')::uuid;
+  END IF;
+  v_out := app._current_unit_id_raw();
+  PERFORM set_config('app.ctx_unit', coalesce(v_out::text, '-'), true);
+  RETURN v_out;
+END $function$;
+
+CREATE OR REPLACE FUNCTION app.unit_scoping_on()
+ RETURNS boolean
+ LANGUAGE plpgsql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE v_cache text := current_setting('app.ctx_unit_scoping', true); v_out boolean;
+BEGIN
+  IF v_cache IS NOT NULL AND v_cache <> '' THEN
+    RETURN v_cache = 't';
+  END IF;
+  v_out := app._unit_scoping_on_raw();
+  PERFORM set_config('app.ctx_unit_scoping', CASE WHEN v_out THEN 't' ELSE 'f' END, true);
+  RETURN v_out;
+END $function$;
+
+COMMENT ON FUNCTION app.current_tenant_id() IS
+  'O tenant da requisição, calculado UMA vez por transação. A regra mora em '
+  'app._current_tenant_id_raw() e não mudou; o que muda é quantas vezes ela '
+  'roda. Sem isto, contar um mês de agenda custava 2,7 ms por linha e os '
+  'painéis estouravam o relógio.';

package/migrations/081_a_permissao_por_unidade_se_resolve_uma_vez_por_unidade.sql

@@ -0,0 +1,88 @@
+-- A permissão por unidade se resolve uma vez por unidade, não por linha.
+--
+-- Depois da 076 o contexto da requisição já não é recalculado por linha, e
+-- contar um mês de agenda caiu de 21,9 s para 11,8 s. Ainda é muito: 1,47 ms
+-- por linha, e a maior parte do que sobrou é `app.has_permission`.
+--
+--     app.has_permission(chave, unidade)   1,002 ms por chamada
+--
+-- Ela não pôde ser memoizada na 076 porque RECEBE ARGUMENTOS — e é a política
+-- que os fornece, com o `unit_id` da linha:
+--
+--     CASE WHEN unit_id IS NULL THEN app.has_permission('agenda.read', NULL)
+--                               ELSE app.has_permission('agenda.read', unit_id) END
+--
+-- Só que os argumentos distintos dentro de UMA consulta são poucos: uma
+-- permissão, e as unidades que aparecem na página. Oito mil linhas produzem
+-- talvez três respostas diferentes — e a função as recalculava oito mil vezes,
+-- cada uma passando por `app.effective_role_id`, que busca o papel efetivo do
+-- usuário naquela unidade.
+--
+-- ── O cache com chave ───────────────────────────────────────────────────────
+--
+-- Um GUC transacional guardando um MAPA jsonb, com chave
+-- `<permissão>|<unidade>`. Ler e escrever um mapa pequeno custa microssegundos
+-- contra o milissegundo da resolução de papel.
+--
+-- O corpo da regra fica intocado em `app._has_permission_raw()`, como na 076 e
+-- pelo mesmo motivo: isto decide quem vê o quê, e uma otimização não é hora de
+-- mexer em regra de acesso. Muda quantas vezes ela roda.
+--
+-- Transacional, então morre com a requisição — o papel de alguém pode mudar a
+-- qualquer momento e a próxima requisição já vê o novo. Dentro de uma
+-- transação ele não muda, e é só isso que o cache assume.
+--
+-- Idempotente.
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 1. A regra, intocada
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION app._has_permission_raw(p_perm text, p_unit uuid DEFAULT NULL::uuid)
+ RETURNS boolean
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+  SELECT EXISTS (
+    SELECT 1
+      FROM app.role_permissions rp
+     WHERE rp.tenant_id = app.current_tenant_id()
+       AND rp.role_id = app.effective_role_id(app.current_tenant_id(), auth.uid(), p_unit)
+       AND rp.permission IN (p_perm, regexp_replace(p_perm, '\.[^.]+$', '.manage'))
+  );
+$function$;
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 2. O invólucro com memória
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION app.has_permission(p_perm text, p_unit uuid DEFAULT NULL::uuid)
+ RETURNS boolean
+ LANGUAGE plpgsql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE
+  v_chave text := p_perm || '|' || coalesce(p_unit::text, '-');
+  v_mapa  jsonb := coalesce(nullif(current_setting('app.ctx_perm', true), '')::jsonb, '{}'::jsonb);
+  v_out   boolean;
+BEGIN
+  IF v_mapa ? v_chave THEN
+    RETURN (v_mapa ->> v_chave)::boolean;
+  END IF;
+  v_out := app._has_permission_raw(p_perm, p_unit);
+  PERFORM set_config('app.ctx_perm',
+                     (v_mapa || jsonb_build_object(v_chave, v_out))::text, true);
+  RETURN v_out;
+EXCEPTION
+  -- Um cache corrompido não pode virar negação de acesso: se o mapa não
+  -- parsear por qualquer motivo, responde a pergunta do jeito caro.
+  WHEN OTHERS THEN RETURN app._has_permission_raw(p_perm, p_unit);
+END $function$;
+
+COMMENT ON FUNCTION app.has_permission(text, uuid) IS
+  'A permissão do usuário, memoizada por (permissão, unidade) dentro da '
+  'transação. A regra mora em app._has_permission_raw() e não mudou. Sem o '
+  'cache ela custava 1 ms por LINHA lida — oito mil linhas de agenda para '
+  'três respostas distintas.';

package/migrations/082_a_cerca_tambem_se_lembra.sql

@@ -0,0 +1,110 @@
+-- A cerca também se lembra.
+--
+-- As 076 e 077 puseram memória no contexto da requisição e na permissão. O
+-- caminho da agenda caiu de 21,9 s para 7,6 s num mês — mas ainda são 0,95 ms
+-- por linha, e todo o resto está nas duas funções que faltaram:
+--
+--     app.has_unit(unidade)          0,445 ms por chamada, POR LINHA
+--     app.owner_scoped(tipo)         0,408 ms
+--
+-- As duas recebem argumento, e por isso não entraram na 076. Mas os argumentos
+-- distintos dentro de uma consulta são poucos — um tipo de recurso, e as
+-- unidades que aparecem na página. `has_unit` responde no máximo 69 coisas
+-- diferentes neste tenant; ela era chamada oito mil vezes.
+--
+-- Mesma forma das anteriores: a regra fica intocada em `app._*_raw()`, e o
+-- invólucro guarda um mapa jsonb num GUC transacional. As duas dividem um mapa só (`app.ctx_acl`), porque respondem à mesma
+-- pergunta de fundo — o que este usuário alcança — e um mapa é mais barato de
+-- ler que dois.
+--
+-- `grants_exist` fica de fora de propósito: os planos mostram que ela já é
+-- avaliada como InitPlan, uma vez por consulta, porque seus argumentos são
+-- constantes. Memoizá-la seria cache sobre cache.
+--
+-- Idempotente.
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 1. As regras, intocadas
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION app._has_unit_raw(p_unit uuid)
+ RETURNS boolean
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+  SELECT p_unit IS NOT NULL
+     AND (app.current_unit_id() IS NULL OR p_unit = app.current_unit_id())
+     AND CASE WHEN app.unit_scoping_on()
+              THEN EXISTS (SELECT 1 FROM app.user_unit_access a
+                            WHERE a.tenant_id = app.current_tenant_id()
+                              AND a.user_id = auth.uid()
+                              AND a.unit_id = p_unit)
+              ELSE EXISTS (SELECT 1 FROM app.units u
+                            WHERE u.id = p_unit AND u.tenant_id = app.current_tenant_id())
+         END;
+$function$
+
+;
+CREATE OR REPLACE FUNCTION app._owner_scoped_raw(p_resource_type text)
+ RETURNS boolean
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+  SELECT coalesce(
+    (SELECT v.owner_scoped FROM app.vertical_owner_scoping v
+       JOIN public.tenants t ON t.role_template = v.role_template
+      WHERE t.id = app.current_tenant_id() AND v.resource_type = p_resource_type),
+    -- no configuration for this vertical: the table's own flag, which defaults
+    -- true. Configuration relaxes; it never tightens by omission.
+    (SELECT r.owner_scoping FROM app.scaffold_registry r WHERE r.resource_type = p_resource_type LIMIT 1),
+    true)
+$function$
+
+;
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 2. Os invólucros com memória
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION app.has_unit(p_unit uuid)
+ RETURNS boolean
+ LANGUAGE plpgsql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE
+  v_chave text := 'u|' || coalesce(p_unit::text, '-');
+  v_mapa  jsonb := coalesce(nullif(current_setting('app.ctx_acl', true), '')::jsonb, '{}'::jsonb);
+  v_out   boolean;
+BEGIN
+  IF v_mapa ? v_chave THEN RETURN (v_mapa ->> v_chave)::boolean; END IF;
+  v_out := app._has_unit_raw(p_unit);
+  PERFORM set_config('app.ctx_acl', (v_mapa || jsonb_build_object(v_chave, v_out))::text, true);
+  RETURN v_out;
+EXCEPTION WHEN OTHERS THEN RETURN app._has_unit_raw(p_unit);
+END $function$;
+
+CREATE OR REPLACE FUNCTION app.owner_scoped(p_resource_type text)
+ RETURNS boolean
+ LANGUAGE plpgsql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE
+  v_chave text := 'o|' || coalesce(p_resource_type, '-');
+  v_mapa  jsonb := coalesce(nullif(current_setting('app.ctx_acl', true), '')::jsonb, '{}'::jsonb);
+  v_out   boolean;
+BEGIN
+  IF v_mapa ? v_chave THEN RETURN (v_mapa ->> v_chave)::boolean; END IF;
+  v_out := app._owner_scoped_raw(p_resource_type);
+  PERFORM set_config('app.ctx_acl', (v_mapa || jsonb_build_object(v_chave, v_out))::text, true);
+  RETURN v_out;
+EXCEPTION WHEN OTHERS THEN RETURN app._owner_scoped_raw(p_resource_type);
+END $function$;
+
+COMMENT ON FUNCTION app.has_unit(uuid) IS
+  'A cerca da unidade, memoizada por unidade dentro da transação. A regra mora '
+  'em app._has_unit_raw() e não mudou. Ela responde no máximo uma coisa por '
+  'unidade da rede, e era chamada uma vez por linha lida.';