@fayz-ai/db 0.14.0 → 0.16.0

package/migrations/083_quem_e_profissional_continua_agendavel.sql

@@ -0,0 +1,32 @@
+-- Quem é profissional continua agendável, mesmo sendo também funcionário.
+--
+-- O reparo da 075 desmarcou `is_bookable` para toda pessoa com linha de ledger
+-- vinda de `employees`, `clients` ou `contacts`. A condição parecia certa e
+-- tinha um furo: **uma pessoa pode ter MAIS DE UMA linha no ledger.**
+--
+-- O V1 tem a mesma pessoa em duas tabelas quando ela atende E é registrada
+-- como funcionária — o que é comum numa clínica: a profissional que também
+-- está na folha. Medido em 20/09/2026, tenant Espaço Facial: 20 pessoas com
+-- duas origens, e **18 profissionais desmarcados** por causa da linha de
+-- funcionário delas.
+--
+-- O efeito era visível na tela: a agenda do Treinamento mostrava 5 colunas
+-- onde o V1 lista 14, e as que faltavam eram exatamente essas.
+--
+-- ── A regra que faltava dizer ───────────────────────────────────────────────
+--
+-- Entre duas origens, quem manda sobre "aparece na agenda" é a que diz SIM.
+-- Ser profissional é o que torna alguém agendável; estar na folha não
+-- desfaz isso. A ausência de uma regra de precedência fez a última linha lida
+-- vencer, que é o pior critério possível — ele depende da ordem do porte.
+--
+-- Idempotente.
+
+UPDATE public.people p
+   SET is_bookable = true
+ WHERE p.tenant_id IS NOT NULL
+   AND NOT p.is_bookable
+   AND EXISTS (SELECT 1 FROM migration.ledger l
+                WHERE l.target_id = p.id
+                  AND l.target_table = 'public.people'
+                  AND l.source_table = 'professionals');

package/migrations/084_quem_atende_em_varias_nao_cabe_numa_coluna.sql

@@ -0,0 +1,60 @@
+-- Quem atende em várias não cabe numa coluna.
+--
+-- A 074 escreveu as tuplas `available_in` só para quem estava com
+-- `people.unit_id` nulo. Ficou pela metade, e a metade que faltou é a que a
+-- view não perdoa. `public.v_bookable_people` diz, na 020:
+--
+--     CASE WHEN p.unit_id IS NOT NULL THEN ARRAY[p.unit_id]
+--          ELSE (as tuplas) END
+--
+-- A coluna VENCE a lista. Então quem o V1 registra em três unidades e chegou
+-- ao V2 com uma na coluna aparece em uma só — e some da agenda das outras
+-- duas. As tuplas que a 074 escrevesse para essa pessoa nunca seriam lidas.
+--
+-- Medido em 20/09/2026: 8 profissionais nessa situação. Na tela, a agenda de
+-- Resende mostrava 3 colunas onde o V1 lista 6, e a de Maricá 3 onde lista 5.
+--
+-- ── O conserto ──────────────────────────────────────────────────────────────
+--
+-- Para quem o V1 lista em MAIS DE UMA unidade: a coluna é limpa e todas as
+-- unidades viram tuplas. É o desenho da 020 aplicado até o fim — coluna para
+-- quem tem uma, lista para quem tem várias.
+--
+-- Quem tem uma só fica como está: a coluna já é a resposta completa, e mexer
+-- nela seria trocar de lugar a mesma informação.
+--
+-- Idempotente.
+
+-- 1. As tuplas de TODAS as unidades de quem tem várias — inclusive a que já
+--    estava na coluna, que sem isto se perderia no passo 2.
+INSERT INTO app.resource_grants
+  (tenant_id, resource_type, resource_id, relation, subject_type, subject_id)
+SELECT DISTINCT p.tenant_id, 'people.person', p.id, 'available_in', 'unit', lu.target_id
+  FROM public.people p
+  JOIN migration.ledger lp
+    ON lp.target_id = p.id AND lp.source_table = 'professionals'
+   AND lp.target_table = 'public.people' AND lp.status = 'migrated'
+  CROSS JOIN LATERAL jsonb_array_elements_text(p.metadata #> '{professional,v1_unit_refs}') AS ref(v1)
+  JOIN migration.ledger lu
+    ON lu.tenant_id = p.tenant_id AND lu.source_table = 'companies'
+   AND lu.target_table = 'app.units' AND lu.status = 'migrated'
+   AND lu.source_numeric_id = ref.v1::bigint
+ WHERE jsonb_typeof(p.metadata #> '{professional,v1_unit_refs}') = 'array'
+   AND jsonb_array_length(p.metadata #> '{professional,v1_unit_refs}') > 1
+   AND ref.v1 ~ '^\d+$'
+ON CONFLICT DO NOTHING;
+
+-- 2. E a coluna sai do caminho, para a lista ser lida.
+UPDATE public.people p
+   SET unit_id = NULL
+ WHERE p.unit_id IS NOT NULL
+   AND jsonb_typeof(p.metadata #> '{professional,v1_unit_refs}') = 'array'
+   AND jsonb_array_length(p.metadata #> '{professional,v1_unit_refs}') > 1
+   AND EXISTS (SELECT 1 FROM migration.ledger l
+                WHERE l.target_id = p.id AND l.source_table = 'professionals'
+                  AND l.target_table = 'public.people')
+   -- Só se as tuplas existirem de fato: limpar a coluna sem ter a lista
+   -- transformaria "atende em três" em "ninguém disse", que aparece em todas.
+   AND EXISTS (SELECT 1 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');

package/migrations/085_a_unidade_do_profissional_vem_de_onde_ele_atende.sql

@@ -0,0 +1,47 @@
+-- A unidade do profissional vem de onde ele atende.
+--
+-- Depois da 080 a agenda ainda não batia: Maricá mostrava 3 colunas onde o V1
+-- lista 5. Os dois que faltavam estavam presos a OUTRA unidade.
+--
+--     Leticia Nogueira · V1 units ["600"] (Maricá)
+--                      · V2 people.unit_id = outra unidade
+--
+-- `people.unit_id` para quem veio de `professionals` não é preenchido a partir
+-- de `units` — o de-para manda `units` para metadata, e a coluna chega por
+-- outro caminho. E como `public.v_bookable_people` prefere a coluna à lista
+-- (ver 020), essa unidade errada apaga a certa.
+--
+-- ── A regra ─────────────────────────────────────────────────────────────────
+--
+-- Onde o profissional atende é o que o V1 diz em `units`, e nada mais. Quando
+-- essa lista tem exatamente UMA unidade, ela vai para a coluna — que é o
+-- caminho barato e o que a 020 desenhou. A 080 já cuidou de quem tem várias.
+--
+-- Só toca em quem veio de `professionals` E tem a lista em metadata: sem a
+-- lista não há o que afirmar, e sobrescrever a coluna com um palpite seria
+-- trocar um erro por outro.
+--
+-- Idempotente.
+
+UPDATE public.people p
+   SET unit_id = alvo.unidade
+  FROM (
+    SELECT p2.id,
+           lu.target_id AS unidade
+      FROM public.people p2
+      JOIN migration.ledger lp
+        ON lp.target_id = p2.id
+       AND lp.source_table = 'professionals'
+       AND lp.target_table = 'public.people'
+      JOIN migration.ledger lu
+        ON lu.tenant_id = p2.tenant_id
+       AND lu.source_table = 'companies'
+       AND lu.target_table = 'app.units'
+       AND lu.status = 'migrated'
+       AND lu.source_numeric_id = (p2.metadata #>> '{professional,v1_unit_refs,0}')::bigint
+     WHERE jsonb_typeof(p2.metadata #> '{professional,v1_unit_refs}') = 'array'
+       AND jsonb_array_length(p2.metadata #> '{professional,v1_unit_refs}') = 1
+       AND (p2.metadata #>> '{professional,v1_unit_refs,0}') ~ '^\d+$'
+  ) alvo
+ WHERE alvo.id = p.id
+   AND p.unit_id IS DISTINCT FROM alvo.unidade;

package/migrations/086_a_ponte_de_clientes_volta_a_existir.sql

@@ -0,0 +1,89 @@
+-- A ponte de clientes volta a existir.
+--
+-- O painel pedia `public.v_clients` e levava **404** em toda carga — a view não
+-- existe. Quatro cartões de cliente ficavam vazios e o console acusava a falha
+-- quatro vezes por visita.
+--
+-- Ela foi removida com razão: juntava `public.clients` com `saas_core.persons`,
+-- e as duas deixaram de existir quando a pessoa virou `public.people`. O que
+-- ficou para trás foi o CÓDIGO — `packages/core/src/data/archetype.ts:182`
+-- mapeia `clients → v_clients`, e o painel do StudioControl a chama em quatro
+-- lugares. Um mapa apontando para um lugar demolido.
+--
+-- Esta migration reconstrói a ponte sobre o que existe hoje, com as mesmas
+-- colunas que o consumidor pede.
+--
+-- ── As três colunas derivadas ───────────────────────────────────────────────
+--
+-- `visits`, `total_spent` e `last_visit` não são campos de pessoa: são
+-- consequência do histórico. Vêm de LATERAL correlacionado por `party_id`, e é
+-- por isso que a migration cria também o índice — sem ele cada cliente pagaria
+-- uma varredura dos 199 mil agendamentos, e o cartão de retenção (que filtra
+-- `visits > 1`) levaria o painel junto.
+--
+-- `security_invoker` OBRIGATÓRIO: sem ele a view roda com os direitos do dono e
+-- as políticas de `public.people` não são avaliadas — que é exatamente como
+-- views vazaram entre tenants antes.
+--
+-- Idempotente.
+
+CREATE INDEX IF NOT EXISTS appointments_party_idx
+  ON public.appointments (tenant_id, party_id)
+  WHERE party_id IS NOT NULL;
+
+COMMENT ON INDEX public.appointments_party_idx IS
+  'Quantas vezes esta pessoa veio. O caminho de v_clients.visits e de toda '
+  'tela que conta o histórico de um cliente.';
+
+DROP VIEW IF EXISTS public.v_clients;
+
+CREATE VIEW public.v_clients
+  WITH (security_invoker = true)
+  AS
+  SELECT
+    p.id,
+    p.tenant_id,
+    p.name,
+    p.email,
+    p.phone,
+    p.document_number,
+    p.avatar_url,
+    p.date_of_birth,
+    p.notes,
+    p.is_active,
+    p.tags,
+    p.unit_id,
+    p.custom_fields ->> 'gender'  AS gender,
+    p.metadata #>> '{crm,origin}' AS origin,
+    coalesce(h.visits, 0)::integer        AS visits,
+    coalesce(g.total_spent, 0)::numeric(14,2) AS total_spent,
+    h.last_visit,
+    p.created_at,
+    p.updated_at
+  FROM public.people p
+  -- Correlacionado em `p.id`: só os agendamentos DESTA pessoa, pelo índice
+  -- acima. Um agregado sem correlação aqui seria refeito por cliente.
+  LEFT JOIN LATERAL (
+    SELECT count(*) AS visits, max(a.starts_at) AS last_visit
+      FROM public.appointments a
+     WHERE a.tenant_id = p.tenant_id
+       AND a.party_id = p.id
+       AND a.status = 'completed'
+  ) h ON true
+  LEFT JOIN LATERAL (
+    SELECT sum(o.total) AS total_spent
+      FROM public.orders o
+     WHERE o.tenant_id = p.tenant_id
+       AND o.party_id = p.id
+       AND o.status = 'completed'
+  ) g ON true
+ WHERE p.kind = 'customer'
+   AND p.merged_into_id IS NULL;
+
+COMMENT ON VIEW public.v_clients IS
+  'A pessoa como CLIENTE, com o que o histórico dela diz: quantas vezes veio, '
+  'quanto gastou, quando foi a última. Ponte para o código que ainda fala o '
+  'vocabulário antigo (archetype.ts mapeia clients → v_clients). O nome '
+  'sobreviveu à tabela que o originou.';
+
+GRANT SELECT ON public.v_clients TO authenticated, service_role;

package/migrations/087_a_liberacao_pergunta_ao_indice_antes_da_funcao.sql

@@ -0,0 +1,79 @@
+-- A liberação pergunta ao índice antes de chamar a função
+--
+-- A 070 pôs dentro de `app.available_in_my_units` a sondagem por RECURSO: sem
+-- tupla nomeando esta linha, devolve `true` sem montar CTE nenhum. A conta
+-- ficou certa e o tempo não: a função é SECURITY DEFINER, e o PostgreSQL NUNCA
+-- incorpora função de definidor no plano. Então cada linha paga a montagem de
+-- um executor inteiro só para chegar naquele `true`.
+--
+-- Com 120.361 pessoas no Espaço Facial isso é o custo da tela de Leads inteira.
+-- Medido, a mesma consulta com e sem esta migração:
+--
+--     lista de leads, unidade Millenium . . . 42.257 ms  →  1.144 ms
+--     lista de leads, rede . . . . . . . . .  47.498 ms  →  5.894 ms
+--
+-- A sondagem sobe para a política, onde ela é expressão e não chamada: o
+-- planejador a incorpora e ela vira uma varredura de índice no prefixo
+-- (tenant_id, resource_type, resource_id) da PK de `app.resource_grants` —
+-- tabela de 1.656 linhas. Quem não tem concessão alguma (118.9 mil das 120.4
+-- mil pessoas) é liberado ali e a função definidora não chega a ser chamada.
+--
+-- `app.has_release_tuple` NÃO é SECURITY DEFINER, e é de propósito: é o que
+-- permite incorporar. Ela lê `app.resource_grants` com os direitos de quem
+-- pergunta, e a política de leitura daquela tabela é o próprio tenant — a
+-- mesma linha que a função definidora enxergaria.
+--
+-- ── O que esta migração NÃO faz, e por quê ──────────────────────────────────
+--
+-- Uma primeira versão deste arquivo mexia em sete políticas de uma vez
+-- (`people`, `products`, `services`, `price_table_items`, `product_variants`,
+-- `service_packages`, `service_package_items`) e descobria o tipo do recurso
+-- lendo a expressão da política com uma regex. Foi um erro, e vale escrever
+-- qual: a expressão tem duas formas — `available_in_my_units('catalog.product',
+-- …)` e `available_in_my_units((SELECT app.current_tenant_id()),
+-- 'catalog.product', …)`. A regex casava só a primeira, e `regexp_replace`
+-- devolve a ENTRADA INTEIRA quando não casa. O tipo do recurso virava o texto
+-- completo da política antiga, `g.resource_type` nunca casava com nada, o
+-- `NOT EXISTS` dava sempre verdadeiro e a linha era liberada para todo mundo.
+-- Cinco asserções de `075_catalog/006_distribution_polarity` pegaram isso — o
+-- "deny wins" parou de vencer.
+--
+-- Então: uma tabela só, a que foi medida, e o tipo escrito por extenso. Não há
+-- texto de SQL sendo interpretado em lugar nenhum deste arquivo.
+--
+-- Idempotente.
+
+CREATE OR REPLACE FUNCTION app.has_release_tuple(p_type text, p_id uuid)
+ RETURNS boolean
+ LANGUAGE sql
+ STABLE
+ SET search_path TO ''
+AS $function$
+  SELECT EXISTS (
+    SELECT 1 FROM app.resource_grants g
+     WHERE g.tenant_id = (SELECT app.current_tenant_id())
+       AND g.resource_type = p_type
+       AND g.resource_id = p_id
+       AND g.relation IN ('available_in', 'unavailable_in')
+  );
+$function$;
+
+REVOKE ALL ON FUNCTION app.has_release_tuple(text, uuid) FROM PUBLIC, anon;
+GRANT EXECUTE ON FUNCTION app.has_release_tuple(text, uuid) TO authenticated, service_role;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_policy WHERE polname = 'people_available_in') THEN
+    RAISE NOTICE 'sem people_available_in neste cluster, nada a fazer';
+    RETURN;
+  END IF;
+
+  ALTER POLICY people_available_in ON public.people USING (
+    (NOT (SELECT app.grants_exist('people.person', ARRAY['available_in', 'unavailable_in'])))
+    OR (unit_id IS NOT NULL)
+    -- A pergunta barata, incorporável, antes da cara. O ramo acrescentado é,
+    -- palavra por palavra, a segunda guarda da própria função.
+    OR (NOT app.has_release_tuple('people.person', people.id))
+    OR (SELECT app.available_in_my_units('people.person', people.id))
+  );
+END $$;

package/migrations/088_quem_pode_executar_o_que_o_porte_criou.sql

@@ -0,0 +1,50 @@
+-- Quem pode executar o que o porte criou
+--
+-- Função nova nasce `EXECUTE` para PUBLIC, e `anon` herda dali. A postura N15c
+-- da bancada diz o que isso significa, e estava vermelha:
+--
+--     N15c: anon can execute nothing callable in schema app     have: 9  want: 0
+--
+-- As que este ramo criou são auxiliares chamadas de
+-- DENTRO de funções SECURITY DEFINER — resolvem identidade com os direitos do
+-- dono e ninguém as chama por fora. A última, `app.has_release_tuple`, é chamada
+-- de FORA: a 087 a pôs dentro de `people_available_in` justamente para o
+-- planejador poder incorporá-la, e isso exige que quem lê a tabela possa
+-- executá-la.
+--
+-- A lista é por extenso, e isso é a lição deste arquivo: uma primeira versão
+-- varria `pg_proc` inteiro nos esquemas `app` e `migration` e revogava de
+-- todos, devolvendo a `authenticated` só uma lista curta que eu supus ser
+-- suficiente. Não era: `app.grants_exist` é citada em política e ficou sem
+-- concessão, e 35 suítes caíram com `permission denied for function
+-- grants_exist`. Revogar em massa é fácil de escrever e impossível de revisar.
+-- Aqui só entram os nomes que este ramo trouxe.
+--
+-- Idempotente.
+
+DO $$
+DECLARE
+  v_fn text;
+BEGIN
+  FOR v_fn IN
+    SELECT p.oid::regprocedure::text
+      FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+     WHERE n.nspname = 'app'
+       AND p.proname IN (
+         '_current_tenant_id_raw', '_current_unit_id_raw', '_has_permission_raw',
+         '_has_unit_raw', '_owner_scoped_raw', '_unit_scoping_on_raw',
+         'requested_unit')
+  LOOP
+    EXECUTE format('REVOKE ALL ON FUNCTION %s FROM PUBLIC, anon, authenticated', v_fn);
+    EXECUTE format('GRANT EXECUTE ON FUNCTION %s TO service_role', v_fn);
+  END LOOP;
+
+  FOR v_fn IN
+    SELECT p.oid::regprocedure::text
+      FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+     WHERE n.nspname = 'app' AND p.proname = 'has_release_tuple'
+  LOOP
+    EXECUTE format('REVOKE ALL ON FUNCTION %s FROM PUBLIC, anon', v_fn);
+    EXECUTE format('GRANT EXECUTE ON FUNCTION %s TO authenticated, service_role', v_fn);
+  END LOOP;
+END $$;

package/migrations/089_a_memoria_de_transacao_nao_serve_para_isto.sql

@@ -0,0 +1,86 @@
+-- A memória de transação não serve para isto
+--
+-- A 080, a 081 e a 082 puseram o contexto da requisição numa GUC de transação
+-- (`set_config(..., true)`) para não resolvê-lo uma vez por linha. A ideia era
+-- boa e o ganho parecia real. A bancada mostrou, em quarenta e uma asserções e
+-- por três caminhos diferentes, que a premissa não se sustenta: uma transação
+-- NÃO é uma pergunta só.
+--
+-- Primeiro a identidade. A bancada troca `request.jwt.claims` entre asserções
+-- — é o que ela precisa fazer para provar que a claim de outro inquilino não
+-- resolve —, e a segunda pergunta recebia a resposta da primeira:
+--
+--     not ok 2 - a claim naming another tenant resolves to no tenant
+--       have: 3fc8bcfd-923c-8f1e-72cf-c8d5dece7bbd     want: NULL
+--
+-- Depois o dado. `UPDATE public.tenants SET unit_scoping_enabled = false` e,
+-- na linha seguinte, `app.unit_scoping_on()` ainda dizia `true`. Vale para
+-- permissão concedida e lida na mesma transação, e para configuração criada e
+-- consultada em seguida — três suítes, três caminhos, todos realistas: uma RPC
+-- que concede e lê é coisa comum.
+--
+-- Houve uma tentativa intermediária de salvar a ideia: digerir o pedido
+-- (claims × cabeçalhos × papel) e invalidar a memória quando a digestão
+-- mudasse. Resolvia a identidade e não resolvia o dado — a digestão resume o
+-- PEDIDO, e o que muda é o BANCO. E mesmo para a identidade ficou incompleta:
+-- `plugin-crm/002_the_lead_offer_cascades` continuou vermelha, porque quem
+-- troca de identidade ali é uma função, por dentro, sem tocar em claim
+-- nenhuma. Medido: com as envolucradoras memorizadas, a suíte aborta; sem
+-- elas, passa inteira.
+--
+-- Então a memória sai. O que fica das três migrações é o que nelas era
+-- separável e correto: a divisão entre a função pública e a `_raw`, que deixa
+-- a resolução num lugar só.
+--
+-- E o desempenho não vinha daqui. Medido no Espaço Facial depois desta
+-- migração — 273.770 negócios, 190.011 orçamentos, 120.361 pessoas:
+--
+--     lista de orçamentos . . . . . . . . . . 21 ms   (índice da 029 do CRM)
+--     quadro do funil, unidade . . . . . . . 443 ms   (junção comum da 026)
+--     lista de leads, unidade . . . . . . . 1.144 ms  (`has_release_tuple`)
+--
+-- Nenhum desses números dependia de guardar resposta entre linhas.
+--
+-- Idempotente.
+
+CREATE OR REPLACE FUNCTION app.has_permission(p_perm text, p_unit uuid DEFAULT NULL::uuid)
+ RETURNS boolean
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$ SELECT app._has_permission_raw(p_perm, p_unit) $function$;
+
+CREATE OR REPLACE FUNCTION app.has_unit(p_unit uuid)
+ RETURNS boolean
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$ SELECT app._has_unit_raw(p_unit) $function$;
+
+CREATE OR REPLACE FUNCTION app.owner_scoped(p_resource_type text)
+ RETURNS boolean
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$ SELECT app._owner_scoped_raw(p_resource_type) $function$;
+
+CREATE OR REPLACE FUNCTION app.unit_scoping_on()
+ RETURNS boolean
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$ SELECT app._unit_scoping_on_raw() $function$;
+
+CREATE OR REPLACE FUNCTION app.current_tenant_id()
+ RETURNS uuid
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$ SELECT app._current_tenant_id_raw() $function$;
+
+CREATE OR REPLACE FUNCTION app.current_unit_id()
+ RETURNS uuid
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO ''
+AS $function$ SELECT app._current_unit_id_raw() $function$;

package/migrations/090_a_marca_tambem_conta_como_mudanca_de_configuracao.sql

@@ -0,0 +1,75 @@
+-- ---------------------------------------------------------------------------
+-- 071_a_marca_tambem_conta_como_mudanca_de_configuracao.sql — o carimbo que o
+-- shell consulta passa a enxergar as settings, e a chave do menu passa a ser a
+-- rota (#280, ADR 0023).
+--
+-- ── §1  O carimbo é cego para metade do que ele carimba ─────────────────────
+-- `app_config()` devolve quatro coisas: branding, settings, ativações e menu.
+-- `tenant_config_version()` — o timestamp que o cliente consulta a cada minuto
+-- para saber se vale reler — olha só DUAS delas: `app.tenant_plugins` e
+-- `app.tenant_nav`.
+--
+-- O resultado é que trocar a logo, a cor, o fuso ou a moeda não chega em aba
+-- nenhuma até alguém recarregar. E o defeito não aparece em teste, porque quem
+-- troca a marca está sempre na tela que acabou de trocá-la: é a SEGUNDA aba,
+-- ou o colega ao lado, que fica com o valor velho.
+--
+-- `tenants.updated_at` já sobe sozinha — `tenant_setting_set` e
+-- `tenant_brand_patch` escrevem em `tenants.settings` e o trigger
+-- `public.handle_updated_at()` carimba. Só faltava lerem juntos.
+--
+-- De passagem, o FULL JOIN sai. Ele cruzava as duas tabelas para depois
+-- descartar quase tudo num max(): dezessete linhas de plugin vezes as linhas de
+-- menu do mesmo tenant, por chamada, uma vez por minuto por aba aberta. Três
+-- selects escalares dizem o mesmo e param no índice.
+--
+-- ── §2  A chave do menu é a ROTA ────────────────────────────────────────────
+-- `app.tenant_nav.entry_key` foi comentada como "`<plugin>:<route>` como o
+-- shell compõe" e o shell nunca compôs assim: ele casa por `item.route`. A
+-- tabela está vazia (nenhum tenant compôs menu ainda), então a grafia ainda
+-- pode ser escolhida em vez de migrada — e a rota é a escolha certa por uma
+-- razão que não é de gosto:
+--
+--   Três dos quatro apps da frota esvaziam a navegação dos plugins com
+--   `hideNav()` e declaram o rail em `FayzAppConfig.pages`. Essas linhas NÃO
+--   TÊM plugin. `<plugin>:<route>` não consegue endereçar a maior parte do
+--   menu que existe hoje; a rota endereça tudo, e é o que o usuário vê na URL.
+--
+-- Comentário, não constraint: a chave continua livre para uma entrada que um
+-- dia não seja uma rota (um link externo, um grupo sem destino).
+--
+-- Idempotente e replay-safe. Nada de DDL destrutivo: uma função substituída e
+-- dois comentários.
+-- ---------------------------------------------------------------------------
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  O carimbo enxerga as settings
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.tenant_config_version(p_tenant uuid DEFAULT NULL::uuid)
+RETURNS timestamptz
+LANGUAGE sql
+STABLE SECURITY DEFINER
+SET search_path TO ''
+AS $function$
+  WITH t AS (SELECT coalesce(p_tenant, app.current_tenant_id()) AS id)
+  SELECT greatest(
+    -- Quais módulos e quais partes deles estão ligados.
+    coalesce((SELECT max(tp.updated_at) FROM app.tenant_plugins tp, t WHERE tp.tenant_id = t.id), 'epoch'::timestamptz),
+    -- A composição do menu deste tenant.
+    coalesce((SELECT max(tn.updated_at) FROM app.tenant_nav tn, t WHERE tn.tenant_id = t.id), 'epoch'::timestamptz),
+    -- Marca, locale, fuso, moeda e toda chave registrada: tudo mora em
+    -- `tenants.settings`, e `app_config()` devolve os dois.
+    coalesce((SELECT te.updated_at FROM public.tenants te, t WHERE te.id = t.id), 'epoch'::timestamptz)
+  );
+$function$;
+
+COMMENT ON FUNCTION public.tenant_config_version(uuid) IS
+  'Um timestamp que se move quando QUALQUER parte de app_config() se move — ativação, menu ou settings (incluindo a marca). O cliente consulta este número; só relê a configuração inteira quando ele anda.';
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  A chave do menu é a rota
+-- ─────────────────────────────────────────────────────────────────────────
+
+COMMENT ON COLUMN app.tenant_nav.entry_key IS
+  'A chave estável da entrada: a ROTA (`/financial`, `/orders/new`), que é como o shell compõe e o que o usuário vê na URL. Não `<plugin>:<route>`: três dos quatro apps desenham o rail em `pages`, e essas linhas não têm plugin nenhum para nomear.';

package/migrations/091_o_shell_tambem_e_configuracao_do_tenant.sql

@@ -0,0 +1,71 @@
+-- ---------------------------------------------------------------------------
+-- 072_o_shell_tambem_e_configuracao_do_tenant.sql — o banco passa a saber COMO
+-- o aplicativo se desenha, não só o que ele tem (#280, ADR 0023).
+--
+-- ── O que faltava ──────────────────────────────────────────────────────────
+-- Depois da 150 o banco sabe QUAIS módulos a conta tem (`app.tenant_plugins`) e
+-- QUAL menu ela compôs (`app.tenant_nav`). O que continuava morando só no
+-- repositório do app é a moldura: rail ou barra no topo, abas ou sub-rail
+-- dentro do módulo, moldura no conteúdo, barra inferior no telefone, e o modo
+-- claro/escuro de partida.
+--
+-- São seis decisões que o `FayzAppConfig` de cada app fixa para TODOS os
+-- inquilinos dele. Uma rede com dez lojas e um escritório que roda o mesmo
+-- aplicativo não tem como pedir topbar no escritório e rail na loja sem um
+-- segundo build — que é exatamente o custo que esta onda existe para matar.
+--
+-- ── Por que chaves, e não uma tabela ───────────────────────────────────────
+-- A 150 já escreveu a regra ao decidir o que NÃO reconstruir: "`tenants.settings`
+-- com o registro em `app.tenant_setting_keys` (076) já governa marca, locale e
+-- toda outra setting com chave". Uma `app.tenant_shell` daria colunas tipadas e
+-- um CHECK de verdade, e em troca duplicaria um mecanismo que já tem tipo,
+-- validação, RPC de leitura e de escrita, permissão e — depois da 071 — o
+-- carimbo de versão. Seis linhas de registro custam nada disso.
+--
+-- O vocabulário fechado, que numa tabela seria CHECK, vira a descrição da
+-- chave: `app.setting_type_ok` valida o TIPO, e o shell ignora um valor que não
+-- conhece em vez de quebrar. Para configuração de aparência, ignorar é a
+-- degradação certa; recusar seria deixar a conta sem moldura nenhuma.
+--
+-- ── reader = core ──────────────────────────────────────────────────────────
+-- Nenhum plugin lê isto: quem lê é a casca. `core` é o mesmo leitor de
+-- `locale`, `timezone` e `branding.*`, que são da mesma natureza.
+--
+-- Idempotente: `app.seed_setting_keys` é upsert por chave.
+-- ---------------------------------------------------------------------------
+
+SELECT app.seed_setting_keys($$[
+  {
+    "key": "shell.layout", "type": "string", "default": null,
+    "reader": "core",
+    "description": "Onde o menu principal vive: 'sidebar' (rail à esquerda), 'topbar' (barra no topo) ou 'minimal' (sem menu). Nulo = o que o aplicativo escolheu."
+  },
+  {
+    "key": "shell.module_nav", "type": "string", "default": null,
+    "reader": "core",
+    "description": "Como as telas de um mesmo módulo se apresentam: 'tabs' (abas no cabeçalho) ou 'sidebar' (sub-itens no rail). Nulo = o que o aplicativo escolheu."
+  },
+  {
+    "key": "shell.content_frame", "type": "boolean", "default": null,
+    "reader": "core",
+    "description": "Se o conteúdo desenha a própria moldura (cartão sobre o fundo) ou encosta na borda. Nulo = o que o aplicativo escolheu."
+  },
+  {
+    "key": "shell.bottom_nav", "type": "boolean", "default": null,
+    "reader": "core",
+    "description": "Barra de abas no rodapé do telefone. Ela é DERIVADA do menu que já passou pelo papel e pelo plano, então desligar aqui tira a barra, nunca acrescenta um destino."
+  },
+  {
+    "key": "shell.nav_transition", "type": "string", "default": null,
+    "reader": "core",
+    "description": "A transição entre telas ('fade', 'slide', 'none'). Nulo = o que o aplicativo escolheu."
+  },
+  {
+    "key": "shell.theme_mode", "type": "string", "default": null,
+    "reader": "core",
+    "description": "O modo de partida: 'light', 'dark' ou 'system'. É o PADRÃO da conta — a escolha de cada pessoa continua vencendo, porque é dela."
+  }
+]$$::jsonb);
+
+COMMENT ON TABLE app.tenant_setting_keys IS
+  'O registro de toda setting com chave que o produto aceita: tipo, valor padrão, quem lê (core ou plugin:<id>) e o alcance. Os VALORES moram em tenants.settings; aqui mora o contrato. Uma chave que não está aqui é recusada por tenant_setting_set.';