@fayz-ai/db 0.13.0 → 0.14.0

package/migrations/017_the_pin_is_checked_against_the_right_workspace.sql

@@ -0,0 +1,139 @@
+-- ---------------------------------------------------------------------------
+-- 017_the_pin_is_checked_against_the_right_workspace.sql — a unidade escolhida
+-- sobrevive ao F5.
+--
+-- O SINTOMA: "troco de unidade, recarrego, e volta pra 'Todas as unidades'".
+--
+-- O CAMINHO: `setActive` grava o pino chamando `public.set_entry_unit`, que
+-- valida antes de gravar:
+--
+--     IF p_unit_id NOT IN (SELECT public.user_unit_ids())
+--       THEN RAISE EXCEPTION 'unidade fora do alcance';
+--
+-- A gravação é silenciosa de propósito — falhar em guardar uma preferência não
+-- é assunto de quem só queria trocar de loja — então a exceção não aparece em
+-- lugar nenhum. `public.user_unit_prefs` fica VAZIA. Na entrada seguinte não há
+-- pino, `resolveEntry` cai no último degrau e responde "todas". A escolha nunca
+-- chegou a existir; só parecia ter chegado, porque a tela trocou na hora.
+--
+-- ── Por que a validação recusava uma unidade que o seletor tinha acabado de
+--    oferecer ─────────────────────────────────────────────────────────────────
+--
+-- `public.user_unit_ids()` errava DUAS vezes, e as duas na mesma direção.
+--
+-- ① NÃO FILTRAVA PELA CONTA. Lia `app.membership_units` só por `user_id`, e os
+--    vínculos de uma pessoa atravessam todas as contas dela. Standing em Espaço
+--    Facial, a função respondia com uma unidade do Espaco Renova Rio e uma da
+--    Clínica Sol. É a MESMA família de bug que a 015 consertou em
+--    `unit_bootstrap`: invisível em conta única, porque lá toda unidade sua é
+--    da única conta que você tem.
+--
+-- ② LIA A TABELA ERRADA. `app.membership_units` guarda só o vínculo EXPLÍCITO,
+--    unidade por unidade. Quem alcança a conta inteira entra por
+--    `app.user_unit_access` com `via = 'all_units'` — que é a tabela que a
+--    própria RLS consulta (`app.has_unit`) e que
+--    `app.refresh_user_unit_access` mantém. As quatro unidades do Espaço Facial
+--    estavam lá, todas com `via = 'all_units'`, e nenhuma em
+--    `membership_units`.
+--
+-- Somados: a função devolvia exatamente as duas unidades erradas e nenhuma das
+-- quatro certas. O seletor (que lê `unit_bootstrap`, já corrigido pela 015)
+-- oferecia as quatro; a gravação, olhando outra tabela e outra conta, recusava
+-- as quatro. Seletor e gravação discordavam sobre o que "minhas unidades"
+-- significa, e quem perdia era a escolha da pessoa.
+--
+-- ── A correção ─────────────────────────────────────────────────────────────
+-- Uma fonte só, a mesma que a RLS usa, recortada pela conta em que a pessoa
+-- está — e a descida na árvore preservada, porque um vínculo numa região
+-- sempre alcançou as filiais abaixo dela.
+--
+-- E `set_entry_unit` passa a validar contra a conta que ELE recebeu, em vez da
+-- conta ambiente da sessão. As duas coincidem hoje; depender disso seria deixar
+-- de pé, no caminho de gravação, a mesma suposição que causou este bug.
+--
+-- NADA AQUI CONCEDE. Isto decide qual pino pode ser GRAVADO. Quem pode ler o
+-- quê continua sendo `app.has_unit` sobre a mesma `app.user_unit_access` — e o
+-- efeito de errar aqui é uma preferência perdida, nunca uma linha revelada.
+-- ---------------------------------------------------------------------------
+
+-- As unidades que esta pessoa alcança DENTRO de uma conta nomeada.
+--
+-- Recebe a conta em vez de deduzi-la: quem chama no caminho de gravação já sabe
+-- em qual está, e passar é o que impede a pergunta de ser respondida sobre
+-- outra.
+CREATE OR REPLACE FUNCTION app.user_unit_ids_in(p_tenant uuid)
+  RETURNS SETOF uuid
+  LANGUAGE sql STABLE SECURITY DEFINER
+  SET search_path TO ''
+  AS $$
+  WITH RECURSIVE seed AS (
+    -- A MESMA tabela que a RLS lê. `membership_units` só conhece o vínculo
+    -- explícito; quem alcança a conta inteira entra por aqui com
+    -- via = 'all_units' e não tem linha lá.
+    SELECT a.unit_id AS id, 0 AS depth
+      FROM app.user_unit_access a
+     WHERE a.user_id = (SELECT auth.uid())
+       AND a.tenant_id = p_tenant
+  ),
+  tree AS (
+    SELECT id, depth FROM seed
+    UNION
+    -- Um vínculo numa região alcança as filiais abaixo. `user_unit_access` já
+    -- costuma chegar expandida; a descida é o que mantém a resposta certa
+    -- quando ela não chegou.
+    SELECT u.id, t.depth + 1
+      FROM app.units u
+      JOIN tree t ON u.parent_unit_id = t.id
+     WHERE u.tenant_id = p_tenant AND t.depth < 8
+  )
+  SELECT id FROM tree;
+$$;
+
+REVOKE ALL ON FUNCTION app.user_unit_ids_in(uuid) FROM PUBLIC;
+GRANT ALL ON FUNCTION app.user_unit_ids_in(uuid) TO authenticated;
+GRANT ALL ON FUNCTION app.user_unit_ids_in(uuid) TO service_role;
+
+COMMENT ON FUNCTION app.user_unit_ids_in(uuid) IS
+  'As unidades que o chamador alcança dentro da conta informada (#017), lidas de app.user_unit_access — a mesma fonte de app.has_unit — e descidas pela árvore. Decide o que pode ser GRAVADO como pino; nunca o que pode ser lido.';
+
+-- A versão sem argumento passa a ser um apelido da de cima sobre a conta da
+-- sessão. Mesma assinatura, mesma resposta para quem já a chamava — só que
+-- agora sobre a conta certa e a tabela certa.
+CREATE OR REPLACE FUNCTION public.user_unit_ids()
+  RETURNS SETOF uuid
+  LANGUAGE sql STABLE SECURITY DEFINER
+  SET search_path TO ''
+  AS $$
+  SELECT app.user_unit_ids_in(app.current_tenant_id());
+$$;
+
+COMMENT ON FUNCTION public.user_unit_ids() IS
+  'As unidades que o chamador alcança na conta em que está (#017). Antes lia app.membership_units sem filtro de conta e devolvia unidades de OUTRO workspace — o que fazia set_entry_unit recusar a unidade que o seletor tinha acabado de oferecer, e a escolha se perder no F5.';
+
+-- A gravação do pino valida contra a conta que recebeu.
+CREATE OR REPLACE FUNCTION public.set_entry_unit(p_tenant_id uuid, p_unit_id uuid, p_device_id text)
+  RETURNS void
+  LANGUAGE plpgsql
+  SET search_path TO 'public', 'pg_temp'
+  AS $$
+BEGIN
+  IF p_device_id IS NULL OR length(trim(p_device_id)) = 0 THEN
+    RAISE EXCEPTION 'device_id obrigatório';
+  END IF;
+
+  -- "Todas as unidades" (nulo) é sempre válido. Uma unidade só é aceita se a
+  -- pessoa a alcança de verdade NESTA conta — a mesma fonte que o RLS usa, e a
+  -- conta que o chamador nomeou, não a que a sessão calhar de ter.
+  IF p_unit_id IS NOT NULL
+     AND p_unit_id NOT IN (SELECT app.user_unit_ids_in(p_tenant_id)) THEN
+    RAISE EXCEPTION 'unidade fora do alcance';
+  END IF;
+
+  INSERT INTO public.user_unit_prefs (user_id, tenant_id, device_id, unit_id, updated_at)
+  VALUES ((SELECT auth.uid()), p_tenant_id, p_device_id, p_unit_id, now())
+  ON CONFLICT (user_id, tenant_id, device_id)
+  DO UPDATE SET unit_id = EXCLUDED.unit_id, updated_at = now();
+END $$;
+
+COMMENT ON FUNCTION public.set_entry_unit(uuid, uuid, text) IS
+  'Guarda em qual unidade a pessoa está, por aparelho (#017 valida contra a conta recebida). Silenciosa para quem chama: falhar em gravar uma preferência não é assunto de quem só queria trocar de loja.';

package/migrations/018_the_bootstrap_says_what_you_reach.sql

@@ -0,0 +1,114 @@
+-- ---------------------------------------------------------------------------
+-- 018_the_bootstrap_says_what_you_reach.sql — a entrada passa a saber quais
+-- unidades a pessoa alcança, e não só quais foram amarradas na mão.
+--
+-- A 017 consertou a GRAVAÇÃO do pino. Ele passou a ser aceito e a chegar em
+-- `public.user_unit_prefs`. E a unidade continuou não persistindo, porque o
+-- problema tinha uma segunda metade, do lado da LEITURA.
+--
+-- ── O que a entrada faz com o pino ─────────────────────────────────────────
+--
+--     const reachable = branchesOnly(expandDown(units, bindings.map(…)), byId)
+--     const entry     = resolveEntry(reachable, { device, account, legacy })
+--
+-- e `resolveEntry` só honra um pino que a pessoa AINDA alcança:
+--
+--     if (canStand(pin.unitId)) return { unitId: pin.unitId, … }
+--     …
+--     return { unitId: undefined, reason: 'all', … }      // o último degrau
+--
+-- A verificação é certa — um pino para uma loja à qual alguém perdeu acesso não
+-- pode ressuscitar o acesso. O que estava errado era o `reachable` contra o qual
+-- ela media.
+--
+-- ── De onde vinha o `reachable` ────────────────────────────────────────────
+-- Do campo `bindings` deste bootstrap, que lê `public.v_unit_members` —
+-- portanto `app.membership_units`, que guarda só o vínculo EXPLÍCITO, unidade
+-- por unidade.
+--
+-- Quem alcança a conta inteira NÃO TEM LINHA LÁ. O acesso dessa pessoa mora em
+-- `app.user_unit_access` com `via = 'all_units'` — a mesma tabela que a RLS lê,
+-- e a mesma que a 017 acabou de adotar. É exatamente o caso do dono do Espaço
+-- Facial: quatro unidades em `user_unit_access`, zero em `membership_units`.
+--
+-- Então `bindings` voltava `[]`, `reachable` era vazio, `canStand` era falso
+-- para qualquer pino, e a entrada caía no último degrau: "todas as unidades".
+-- Toda vez. O menu de unidades disfarçava a metade dele — ele tem um recuo
+-- (`myUnitIds.length > 0 ? myUnitIds : todas`) que fazia o seletor mostrar as
+-- quatro mesmo assim. `resolveEntry` não tem recuo nenhum, e é ele que decide
+-- onde a tela abre.
+--
+-- ── A correção ─────────────────────────────────────────────────────────────
+-- O bootstrap passa a dizer as duas coisas, porque são duas coisas:
+--
+--   • `bindings`  — o que foi amarrado na mão. Continua sendo isto, sem
+--                   mudança: é o que a aba "Unidades" de uma pessoa edita.
+--   • `reachable` — o que a pessoa ALCANÇA de verdade, de
+--                   `app.user_unit_ids_in` (#017). É contra isto que um pino
+--                   deve ser medido, porque é isto que o Postgres vai obedecer.
+--
+-- Confundir os dois é o bug: um deles é a intenção que alguém digitou, o outro
+-- é o alcance que o banco reconhece, e só o segundo responde "posso ficar aqui?".
+--
+-- Campo NOVO e aditivo de propósito: um cliente que ainda não conhece
+-- `reachable` continua lendo `bindings` como sempre leu.
+--
+-- NADA AQUI CONCEDE. `reachable` é a leitura de uma tabela que a RLS já usa
+-- para decidir, e serve para escolher onde a tela ABRE. Errar aqui abre na
+-- unidade errada — e as linhas que aparecerem lá continuam sendo as que o
+-- Postgres deixar aparecer.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION public.unit_bootstrap(p_tenant_id uuid, p_device_id text DEFAULT NULL::text)
+ RETURNS jsonb
+ LANGUAGE sql
+ STABLE
+ SET search_path TO 'public', 'pg_temp'
+AS $function$
+  SELECT jsonb_build_object(
+    'mode', COALESCE((
+      SELECT t.unit_scoping_enabled FROM public.tenants t WHERE t.id = p_tenant_id
+    ), false),
+    'units', COALESCE((
+      SELECT jsonb_agg(to_jsonb(l) ORDER BY l.is_headquarters DESC NULLS LAST, l.name)
+        FROM public.v_units l WHERE l.tenant_id = p_tenant_id
+    ), '[]'::jsonb),
+    -- O vínculo EXPLÍCITO, como sempre. A 015 é que lhe deu o filtro de conta.
+    'bindings', COALESCE((
+      SELECT jsonb_agg(jsonb_build_object('location_id', lm.location_id, 'role', lm.role))
+        FROM public.v_unit_members lm
+       WHERE lm.user_id = (SELECT auth.uid())
+         AND lm.tenant_id = p_tenant_id
+    ), '[]'::jsonb),
+    -- O ALCANCE. Inclui quem entra pela conta inteira (`via = 'all_units'`), que
+    -- é justamente quem não tem vínculo explícito nenhum.
+    'reachable', COALESCE((
+      SELECT jsonb_agg(u) FROM app.user_unit_ids_in(p_tenant_id) u
+    ), '[]'::jsonb),
+    'scoped', COALESCE((
+      SELECT jsonb_object_agg(sr.resource_table, jsonb_build_object(
+               'unit_column', sr.unit_column, 'shareable', sr.shareable))
+        FROM public.scoped_resources sr
+    ), '{}'::jsonb),
+    'device_pin', (
+      SELECT p.unit_id FROM public.user_unit_prefs p
+       WHERE p.user_id = (SELECT auth.uid()) AND p.tenant_id = p_tenant_id AND p.device_id = p_device_id
+    ),
+    'device_pin_set', EXISTS (
+      SELECT 1 FROM public.user_unit_prefs p
+       WHERE p.user_id = (SELECT auth.uid()) AND p.tenant_id = p_tenant_id AND p.device_id = p_device_id
+    ),
+    'account_pin', (
+      SELECT p.unit_id FROM public.user_unit_prefs p
+       WHERE p.user_id = (SELECT auth.uid()) AND p.tenant_id = p_tenant_id
+       ORDER BY p.updated_at DESC LIMIT 1
+    ),
+    'account_pin_set', EXISTS (
+      SELECT 1 FROM public.user_unit_prefs p
+       WHERE p.user_id = (SELECT auth.uid()) AND p.tenant_id = p_tenant_id
+    )
+  );
+$function$;
+
+COMMENT ON FUNCTION public.unit_bootstrap(uuid, text) IS
+  'Tudo que a entrada precisa, numa viagem. `bindings` é o vínculo explícito (o que a aba Unidades edita); `reachable` (#018) é o alcance real, de app.user_unit_ids_in — inclui quem entra pela conta inteira e não tem vínculo nenhum. É contra `reachable` que um pino de entrada deve ser medido.';

package/migrations/019_distributing_one_row_stops_costing_the_table.sql

@@ -0,0 +1,245 @@
+-- ---------------------------------------------------------------------------
+-- 019_distributing_one_row_stops_costing_the_table.sql — usar a distribuição
+-- para UMA linha deixa de custar o preço dela em TODAS.
+--
+-- A 016 tirou `app.available_in_my_units` de dentro do laço da RLS com uma
+-- guarda de TIPO: "este tenant tem alguma tupla de distribuição para
+-- `people.person`?". Não depende da linha, então vira InitPlan e roda uma vez.
+-- `/clients` foi de 10.036ms para 15ms.
+--
+-- A guarda de tipo tem um degrau, e o Espaço Facial chegou nele no mesmo dia.
+--
+-- ── O degrau ───────────────────────────────────────────────────────────────
+-- 128 profissionais da rede atendem em MAIS DE UMA unidade. Uma coluna
+-- `people.unit_id` guarda uma unidade, não seis — quem atende em várias se
+-- descreve por tuplas `available_in`, que é para isso que elas existem.
+--
+-- Só que a guarda da 016 responde por TIPO, e cliente e profissional são o
+-- mesmo tipo: `people.person`. Gravar os 128 tornaria
+-- `grants_exist('people.person')` verdadeiro para o tenant inteiro, e os 3.545
+-- CLIENTES — todos sem unidade — voltariam a pagar 2,5ms cada um. `/clients`
+-- voltaria aos 10s por causa de um vínculo de equipe.
+--
+-- Uma otimização que se desliga sozinha quando o recurso que ela protege começa
+-- a ser usado não é uma otimização, é uma armadilha com prazo.
+--
+-- ── Três coisas, medidas uma a uma ─────────────────────────────────────────
+-- Depois de gravar os vínculos, `/clients` foi a 10.036ms. As três correções,
+-- na ordem em que o planejador as entregou:
+--
+--   ① A PERGUNTA CERTA É SOBRE A LINHA, não sobre o tipo: "ESTA linha tem
+--      alguma tupla?". Sondagem no prefixo (tenant_id, resource_type,
+--      resource_id) da PK. A derivação da 016 continua valendo palavra por
+--      palavra, só que verificada em vez de deduzida.        10.036ms → 2.110ms
+--
+--   ② `app.current_tenant_id()` SAI DO LAÇO. Ela é plpgsql, lê o JWT, casa um
+--      regex e consulta `memberships` — e a guarda a chamava por linha. Com o
+--      tenant recebido por parâmetro e `(select app.current_tenant_id())` na
+--      POLÍTICA, ela vira InitPlan.                            2.110ms → 690ms
+--
+--   ③ A CHAMADA EM SI é o que sobrou: 0,1ms por linha só para o Postgres
+--      trocar o contexto de `SECURITY DEFINER`, e uma função assim nunca é
+--      inlinada. Então a lista de linhas distribuídas é resolvida UMA vez
+--      (`app.released_ids`, um InitPlan materializado) e o teste por linha vira
+--      `id <> ALL (…)` — uma comparação em memória.               690ms → 19ms
+--
+-- (Os 641ms que o EXPLAIN ANALYZE mostrava no fim eram instrumentação: com
+-- SubPlan por linha, medir custa mais do que executar. O tempo de parede da
+-- consulta, cronometrado sem EXPLAIN, é 19ms.)
+--
+-- ── A forma final da política ──────────────────────────────────────────────
+-- Três guardas antes da regra cara, e NENHUMA delas menciona coluna — as três
+-- são InitPlan:
+--
+--   1. o tenant distribui algo deste tipo?
+--   2. a linha tem unidade própria? (então é localizada, não distribuída)
+--   3. a linha está na lista das que têm tupla?
+--
+-- Só quem passa pelas três paga a resolução completa, que é o preço correto de
+-- um recurso que realmente foi distribuído.
+-- ---------------------------------------------------------------------------
+
+-- ① As linhas que TÊM regra, resolvidas de uma vez. Sem id de linha no
+--    argumento: é o que permite ao planejador materializá-la e reusá-la.
+CREATE OR REPLACE FUNCTION app.released_ids(p_tenant uuid, p_type text)
+  RETURNS SETOF uuid LANGUAGE sql STABLE SECURITY DEFINER SET search_path TO ''
+  AS $fn$
+  SELECT DISTINCT g.resource_id FROM app.resource_grants g
+   WHERE g.tenant_id = p_tenant AND g.resource_type = p_type
+     AND g.relation IN ('available_in', 'unavailable_in');
+$fn$;
+
+REVOKE ALL ON FUNCTION app.released_ids(uuid, text) FROM PUBLIC;
+GRANT ALL ON FUNCTION app.released_ids(uuid, text) TO authenticated;
+GRANT ALL ON FUNCTION app.released_ids(uuid, text) TO service_role;
+
+COMMENT ON FUNCTION app.released_ids(uuid, text) IS
+  'As linhas deste tipo que têm alguma tupla de distribuição (#019). Existe para ser InitPlan: resolvida uma vez, o teste por linha vira `id <> ALL (…)` em memória em vez de uma chamada SECURITY DEFINER, que custa 0,1ms só de trocar o contexto.';
+
+-- ② As mesmas perguntas, recebendo o tenant em vez de deduzi-lo. A dedução é
+--    cara e não depende da linha; quem chama de dentro de uma política já a
+--    tem resolvida num InitPlan.
+CREATE OR REPLACE FUNCTION app.grants_exist(p_tenant uuid, p_type text, p_relations text[])
+  RETURNS boolean LANGUAGE sql STABLE SECURITY DEFINER SET search_path TO ''
+  AS $fn$
+  SELECT EXISTS (SELECT 1 FROM app.resource_grants g
+                  WHERE g.tenant_id = p_tenant AND g.resource_type = p_type
+                    AND g.relation = ANY (p_relations));
+$fn$;
+
+REVOKE ALL ON FUNCTION app.grants_exist(uuid, text, text[]) FROM PUBLIC;
+GRANT ALL ON FUNCTION app.grants_exist(uuid, text, text[]) TO authenticated;
+GRANT ALL ON FUNCTION app.grants_exist(uuid, text, text[]) TO service_role;
+
+CREATE OR REPLACE FUNCTION app.unit_release_verdict(p_tenant uuid, p_type text, p_id uuid, p_unit uuid)
+  RETURNS text LANGUAGE sql STABLE SECURITY DEFINER SET search_path TO ''
+  AS $fn$
+  SELECT coalesce(
+    (SELECT CASE WHEN bool_or(g.relation = 'unavailable_in') THEN 'deny' ELSE 'allow' END
+       FROM app.unit_chain(p_unit) c
+       JOIN app.resource_grants g
+         ON g.tenant_id = p_tenant
+        AND g.resource_type = p_type AND g.resource_id = p_id
+        AND g.subject_type = 'unit' AND g.subject_id = c.unit_id
+        AND g.relation IN ('available_in', 'unavailable_in')
+      GROUP BY c.depth ORDER BY c.depth LIMIT 1),
+    'none');
+$fn$;
+
+REVOKE ALL ON FUNCTION app.unit_release_verdict(uuid, text, uuid, uuid) FROM PUBLIC;
+GRANT ALL ON FUNCTION app.unit_release_verdict(uuid, text, uuid, uuid) TO authenticated;
+GRANT ALL ON FUNCTION app.unit_release_verdict(uuid, text, uuid, uuid) TO service_role;
+
+-- A regra completa, com o tenant recebido e a guarda de LINHA na frente. Corpo
+-- idêntico ao da 000 a partir do `WITH me`.
+CREATE OR REPLACE FUNCTION app.available_in_my_units(p_tenant uuid, p_type text, p_id uuid)
+  RETURNS boolean LANGUAGE sql STABLE SECURITY DEFINER SET search_path TO ''
+  AS $fn$
+  SELECT CASE
+    WHEN NOT EXISTS (
+      SELECT 1 FROM app.resource_grants g
+       WHERE g.tenant_id = p_tenant AND g.resource_type = p_type AND g.resource_id = p_id
+         AND g.relation IN ('available_in', 'unavailable_in')
+    ) THEN true
+    ELSE (
+      WITH me AS (
+        SELECT 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
+         WHERE g.tenant_id = p_tenant 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 = p_tenant AND m.user_id = me.uid AND m.active
+                  UNION
+                  SELECT mu.role_override_id FROM app.membership_units mu
+                   WHERE mu.tenant_id = p_tenant 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 = p_tenant 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_tenant, 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;
+$fn$;
+
+REVOKE ALL ON FUNCTION app.available_in_my_units(uuid, text, uuid) FROM PUBLIC;
+GRANT ALL ON FUNCTION app.available_in_my_units(uuid, text, uuid) TO authenticated;
+GRANT ALL ON FUNCTION app.available_in_my_units(uuid, text, uuid) TO service_role;
+
+-- A forma de dois argumentos continua existindo para quem chama de fora de uma
+-- política (RPCs, views) e não tem o tenant à mão.
+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 $fn$
+  SELECT app.available_in_my_units(app.current_tenant_id(), p_type, p_id);
+$fn$;
+
+COMMENT ON FUNCTION app.available_in_my_units(p_type text, p_id uuid) IS
+  'A regra de distribuição, resolvida ao longo da árvore de unidades (#223 + #227): sem tupla ⇒ em todo lugar; havendo, o nível mais próximo da cadeia de cada unidade no escopo decide, e negar vence permitir naquele nível. Desde #019 delega para a forma que recebe o tenant, para que a dedução dele não aconteça por linha.';
+
+-- ③ O gerador da política de distribuição, com as três guardas na frente.
+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 $fn$
+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 ordem das guardas é o desenho (ver o cabeçalho): as três primeiras não
+    -- mencionam coluna nenhuma e por isso são InitPlan. `(select
+    -- app.current_tenant_id())` aparece três vezes e é avaliada uma.
+    EXECUTE format(
+      'CREATE POLICY %I ON %s AS RESTRICTIVE FOR SELECT TO authenticated USING ('
+      || 'NOT (select app.grants_exist((select app.current_tenant_id()), %L, ARRAY[''available_in'', ''unavailable_in''])) '
+      || 'OR %s%I <> ALL (select app.released_ids((select app.current_tenant_id()), %L)) '
+      || 'OR (select app.available_in_my_units((select app.current_tenant_id()), %L, %I)))',
+      v_policy, v_q, v_rt,
+      CASE WHEN p_unit_escape THEN 'unit_id IS NOT NULL OR ' ELSE '' END,
+      p_key_column, v_rt, 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 $fn$;
+
+-- Reescrever o que já está no banco: o texto das políticas existentes foi
+-- assado quando elas foram criadas.
+DO $do$
+DECLARE r record; v_n int := 0;
+BEGIN
+  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 '019: % política(s) de distribuição regerada(s)', v_n;
+END $do$;

package/migrations/020_the_agenda_asks_where_someone_works.sql

@@ -0,0 +1,81 @@
+-- ---------------------------------------------------------------------------
+-- 020_the_agenda_asks_where_someone_works.sql — a agenda de uma unidade passa a
+-- mostrar quem trabalha NELA.
+--
+-- O SINTOMA, depois de migrar as 61 filiais e carimbar a equipe: standing em
+-- Brisamar, a agenda mostrava 404 profissionais de 739. Filtrou — e não pareceu
+-- ter filtrado, porque 396 dos 404 são pessoas cujo `unit_id` é NULL.
+--
+-- ── Por que NULL passa por todo filtro ─────────────────────────────────────
+-- `people` é `shareable` no registro (`public.scoped_resources`), e para um
+-- recurso compartilhável `unit_id IS NULL` quer dizer "é da rede inteira". A
+-- regra é certa e existe por um bom motivo: o Botox vendido em toda parte
+-- continua aparecendo em Ipanema.
+--
+-- Só que uma PESSOA sem unidade não é "atende em toda parte". É NÃO LOTADA —
+-- 268 delas porque o V1 nunca disse onde trabalham, e as outras 128 porque
+-- atendem em várias e se descrevem por tuplas `available_in`, não por coluna.
+-- Os dois casos caem no mesmo NULL, e a coluna sozinha não sabe distinguir.
+--
+-- Uma agenda que mostra 396 colunas de gente que pode nem pisar naquela loja
+-- não está compartilhando ninguém; está deixando de responder a pergunta que
+-- lhe fizeram.
+--
+-- ── O que esta view acrescenta ─────────────────────────────────────────────
+-- `unit_ids`: ONDE a pessoa efetivamente atende, juntando as duas formas de
+-- dizer isso que hoje vivem em lugares diferentes —
+--
+--   • a coluna `unit_id`, para quem tem uma só;
+--   • as tuplas `available_in` de `app.resource_grants`, para quem tem várias.
+--
+-- E `NULL` quando não há nem uma nem outra, que agora é uma resposta DISTINTA
+-- de "está em todas": é "ninguém disse". A agenda esconde essas de uma unidade
+-- e as mostra em "todas as unidades", que é onde alguém pode notar a falta e
+-- corrigi-la. Antes elas eram invisíveis por excesso.
+--
+-- O filtro vira `unit_ids=cs.{id}` no PostgREST — contenção de array, sem
+-- enumerar unidade nenhuma no navegador, que é a única coisa que este desenho
+-- se recusa a fazer.
+--
+-- security_invoker OBRIGATÓRIO: sem ele a view roda com os direitos do dono e
+-- as políticas de `people` não são avaliadas — que é exatamente como views
+-- vazaram entre tenants antes. Com ele, esta view não pode mostrar uma linha
+-- que a tabela recusaria.
+-- ---------------------------------------------------------------------------
+
+DROP VIEW IF EXISTS public.v_bookable_people;
+
+CREATE VIEW public.v_bookable_people
+  WITH (security_invoker = true)
+  AS
+  SELECT
+    p.id,
+    p.tenant_id,
+    p.kind,
+    p.name,
+    p.avatar_url,
+    p.is_active,
+    p.is_bookable,
+    p.unit_id,
+    -- Uma unidade própria já é a resposta completa; a lista de tuplas só é
+    -- consultada para quem não tem coluna. `NULL` é "ninguém disse", e é
+    -- deliberadamente diferente de um array vazio.
+    CASE
+      WHEN p.unit_id IS NOT NULL THEN ARRAY[p.unit_id]
+      ELSE (
+        SELECT array_agg(DISTINCT g.subject_id)
+          FROM app.resource_grants g
+         WHERE g.tenant_id = p.tenant_id
+           AND g.resource_type = 'people.person'
+           AND g.resource_id = p.id
+           AND g.relation = 'available_in'
+           AND g.subject_type = 'unit'
+      )
+    END AS unit_ids
+  FROM public.people p;
+
+REVOKE ALL ON public.v_bookable_people FROM public, anon;
+GRANT SELECT ON public.v_bookable_people TO authenticated, service_role;
+
+COMMENT ON VIEW public.v_bookable_people IS
+  'Pessoas com `unit_ids`: onde cada uma efetivamente atende (#020), juntando a coluna `unit_id` de quem tem uma só com as tuplas `available_in` de quem tem várias. NULL = ninguém disse, que é diferente de "em todas" — a agenda de uma unidade esconde essas, e "todas as unidades" as mostra. security_invoker: as políticas de public.people continuam decidindo o que é visível.';