@fayz-ai/db 0.14.0 → 0.16.0

package/migrations/061_a_linha_sem_data_pode_ser_estrutura.sql

@@ -0,0 +1,253 @@
+-- Uma linha sem data pode ser estrutura, e estrutura não tem período.
+--
+-- `analytics_run` recorta todo read model pela janela do seletor:
+--
+--     competence_month >= :de  AND  competence_month <= :ate
+--
+-- Uma linha com a data NULA falha as duas comparações e desaparece. Para um
+-- FATO isso é o certo — "em que mês isto aconteceu" não tem resposta, e somá-lo
+-- em qualquer janela seria inventar uma.
+--
+-- Mas nem toda linha de um read model é um fato. A DRE precisa da ÁRVORE DO
+-- PLANO DE CONTAS junto com os lançamentos: a conta que não teve movimento no
+-- exercício aparece na tela do V1 com travessão em todos os meses, porque um
+-- plano de contas é a declaração do que o negócio acompanha. A conta zerada é
+-- uma resposta ("não houve"); a conta ausente é uma pergunta que ninguém fez.
+--
+-- Sem isto, o ramo 1 inteiro — as 45 contas de receita do tenant Pertinho do
+-- Céu — sumia do relatório e a árvore começava no 2.
+--
+-- ── Por que uma coluna, e não mudar a regra para todos ───────────────────────
+--
+-- Fazer `(data IS NULL OR data >= :de)` valer para todo read model mudaria, em
+-- silêncio, o que cada relatório do produto responde: uma linha sem data
+-- passaria a contar em QUALQUER janela. Hoje ela não conta em nenhuma, e para a
+-- maioria dos modelos isso é a resposta certa.
+--
+-- `include_undated` deixa a exceção onde ela se lê: na linha do registro, ao
+-- lado do nome do modelo. O padrão é `false`, então nenhum relatório existente
+-- muda de comportamento por causa deste arquivo.
+--
+-- Idempotente.
+
+ALTER TABLE public.analytics_read_models
+  ADD COLUMN IF NOT EXISTS include_undated boolean NOT NULL DEFAULT false;
+
+COMMENT ON COLUMN public.analytics_read_models.include_undated IS
+  'Linha com a coluna de data NULA atravessa o filtro de período em vez de ser '
+  'descartada. Para modelos que emitem ESTRUTURA junto com fato — a árvore do '
+  'plano de contas na DRE, por exemplo, onde a conta sem movimento ainda '
+  'precisa de linha. Padrão false: um fato sem data não pertence a janela '
+  'nenhuma.';
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- O motor passa a consultar a coluna
+-- ─────────────────────────────────────────────────────────────────────────────
+--
+-- Corpo extraído do próprio cluster com `pg_get_functiondef` e alterado em dois
+-- pontos — os dois `format()` do recorte de data. Nada mais desta função muda.
+
+CREATE OR REPLACE FUNCTION public.analytics_run(p_source text, p_tenant_id uuid DEFAULT NULL::uuid, p_from timestamp with time zone DEFAULT NULL::timestamp with time zone, p_to timestamp with time zone DEFAULT NULL::timestamp with time zone, p_dimensions jsonb DEFAULT '[]'::jsonb, p_measures jsonb DEFAULT '[]'::jsonb, p_filters jsonb DEFAULT '{}'::jsonb, p_search text DEFAULT NULL::text, p_search_columns text[] DEFAULT NULL::text[], p_sort text DEFAULT NULL::text, p_dir text DEFAULT 'desc'::text, p_limit integer DEFAULT 500, p_offset integer DEFAULT 0)
+ RETURNS jsonb
+ LANGUAGE plpgsql
+ STABLE
+ SET search_path TO 'public', 'extensions', 'pg_temp'
+AS $function$
+DECLARE
+  v_model      public.analytics_read_models%ROWTYPE;
+  v_where      text[] := ARRAY[]::text[];
+  v_where_sql  text;
+  v_select     text[] := ARRAY[]::text[];
+  v_group      text[] := ARRAY[]::text[];
+  v_agg_only   text[] := ARRAY[]::text[];
+  v_dim        jsonb;
+  v_meas       jsonb;
+  v_key        text;
+  v_col        text;
+  v_grain      text;
+  v_agg        text;
+  v_expr       text;
+  v_filter_key text;
+  v_filter_val jsonb;
+  v_search_ors text[] := ARRAY[]::text[];
+  v_sort_sql   text := '';
+  v_rows       jsonb;
+  v_summary    jsonb;
+  v_total      bigint;
+  v_limit      int := LEAST(GREATEST(COALESCE(p_limit, 500), 1), 5000);
+  v_offset     int := GREATEST(COALESCE(p_offset, 0), 0);
+BEGIN
+  -- 8.1 The source must be registered. Not "look like a read model" — registered.
+  SELECT * INTO v_model FROM public.analytics_read_models WHERE name = p_source;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'analytics: % is not a registered read model', p_source USING ERRCODE = '42P01';
+  END IF;
+
+  -- 8.2 Tenant + date window. The date column comes from the registry, so a
+  --     caller cannot redirect the range onto some other timestamp.
+  IF p_tenant_id IS NOT NULL THEN
+    v_where := v_where || format('%I = %L', v_model.tenant_column, p_tenant_id);
+  END IF;
+  IF p_from IS NOT NULL THEN
+    v_where := v_where || CASE WHEN coalesce(v_model.include_undated, false)
+      THEN format('(%I IS NULL OR %I >= %L)', v_model.date_column, v_model.date_column, p_from)
+      ELSE format('%I >= %L', v_model.date_column, p_from) END;
+  END IF;
+  IF p_to IS NOT NULL THEN
+    v_where := v_where || CASE WHEN coalesce(v_model.include_undated, false)
+      THEN format('(%I IS NULL OR %I <= %L)', v_model.date_column, v_model.date_column, p_to)
+      ELSE format('%I <= %L', v_model.date_column, p_to) END;
+  END IF;
+
+  -- 8.3 Equality / IN filters.
+  FOR v_filter_key, v_filter_val IN SELECT key, value FROM jsonb_each(COALESCE(p_filters, '{}'::jsonb))
+  LOOP
+    CONTINUE WHEN v_filter_val IS NULL OR jsonb_typeof(v_filter_val) = 'null';
+    v_col := public.analytics_assert_column(p_source, v_filter_key);
+
+    IF jsonb_typeof(v_filter_val) = 'array' THEN
+      CONTINUE WHEN jsonb_array_length(v_filter_val) = 0;
+      v_where := v_where || format(
+        '%I::text = ANY (SELECT jsonb_array_elements_text(%L::jsonb))', v_col, v_filter_val);
+    ELSE
+      v_where := v_where || format('%I::text = %L', v_col, v_filter_val #>> '{}');
+    END IF;
+  END LOOP;
+
+  -- 8.4 Free-text search across the caller's declared text columns.
+  IF p_search IS NOT NULL AND length(btrim(p_search)) > 0 AND p_search_columns IS NOT NULL THEN
+    FOREACH v_col IN ARRAY p_search_columns LOOP
+      v_col := public.analytics_assert_column(p_source, v_col);
+      v_search_ors := v_search_ors || format('%I::text ILIKE %L', v_col, '%' || btrim(p_search) || '%');
+    END LOOP;
+    IF array_length(v_search_ors, 1) > 0 THEN
+      v_where := v_where || ('(' || array_to_string(v_search_ors, ' OR ') || ')');
+    END IF;
+  END IF;
+
+  v_where_sql := CASE WHEN array_length(v_where, 1) > 0
+                      THEN ' WHERE ' || array_to_string(v_where, ' AND ')
+                      ELSE '' END;
+
+  -- 8.5 Dimensions. A grain turns a timestamp into a bucket; without one the
+  --     raw column value is the group.
+  FOR v_dim IN SELECT * FROM jsonb_array_elements(COALESCE(p_dimensions, '[]'::jsonb))
+  LOOP
+    v_key   := v_dim ->> 'key';
+    v_col   := public.analytics_assert_column(p_source, v_key);
+    v_grain := v_dim ->> 'grain';
+
+    IF v_grain IS NULL THEN
+      v_expr := format('%I', v_col);
+    ELSIF v_grain IN ('hour','day','week','month','quarter','year') THEN
+      v_expr := format('date_trunc(%L, %I)', v_grain, v_col);
+    ELSE
+      RAISE EXCEPTION 'analytics: unsupported time grain %', v_grain USING ERRCODE = '22023';
+    END IF;
+
+    v_select := v_select || format('%s AS %I', v_expr, v_key);
+    v_group  := v_group  || v_expr;
+  END LOOP;
+
+  -- 8.6 Measures. Fixed aggregate vocabulary — anything else is rejected rather
+  --     than passed through, which is the difference between a parameter and an
+  --     injection point. 'ratio' is deliberately absent: it is derived on the
+  --     client from two real measures so ratio-of-sums never degrades into
+  --     avg-of-ratios.
+  FOR v_meas IN SELECT * FROM jsonb_array_elements(COALESCE(p_measures, '[]'::jsonb))
+  LOOP
+    v_key := v_meas ->> 'key';
+    IF v_key IS NULL OR v_key !~ '^[a-z_][a-z0-9_]*$' THEN
+      RAISE EXCEPTION 'analytics: malformed measure key %', v_key USING ERRCODE = '22023';
+    END IF;
+    v_agg := lower(COALESCE(v_meas ->> 'agg', 'sum'));
+
+    IF v_agg = 'count' THEN
+      v_expr := 'count(*)';
+    ELSE
+      v_col := public.analytics_assert_column(p_source, COALESCE(v_meas ->> 'column', v_key));
+      v_expr := CASE v_agg
+        WHEN 'sum'            THEN format('sum(%I)', v_col)
+        WHEN 'avg'            THEN format('avg(%I)', v_col)
+        WHEN 'min'            THEN format('min(%I)', v_col)
+        WHEN 'max'            THEN format('max(%I)', v_col)
+        WHEN 'count_distinct' THEN format('count(DISTINCT %I)', v_col)
+        ELSE NULL
+      END;
+      IF v_expr IS NULL THEN
+        RAISE EXCEPTION 'analytics: unsupported aggregate %', v_agg USING ERRCODE = '22023';
+      END IF;
+    END IF;
+
+    v_select   := v_select   || format('%s AS %I', v_expr, v_key);
+    v_agg_only := v_agg_only || format('%s AS %I', v_expr, v_key);
+  END LOOP;
+
+  -- 8.7 No measures ⇒ a raw detail listing (the classic tabular report).
+  IF array_length(v_agg_only, 1) IS NULL AND array_length(v_group, 1) IS NULL THEN
+    v_select := ARRAY['*'];
+  END IF;
+
+  -- 8.8 Sort. Must be one of the things actually selected — an alias, not an
+  --     arbitrary expression.
+  IF p_sort IS NOT NULL AND p_sort ~ '^[a-z_][a-z0-9_]*$' THEN
+    IF EXISTS (SELECT 1 FROM jsonb_array_elements(COALESCE(p_measures,'[]'::jsonb)) m WHERE m->>'key' = p_sort)
+       OR EXISTS (SELECT 1 FROM jsonb_array_elements(COALESCE(p_dimensions,'[]'::jsonb)) d WHERE d->>'key' = p_sort)
+       OR (array_length(v_agg_only,1) IS NULL AND array_length(v_group,1) IS NULL)
+    THEN
+      IF array_length(v_agg_only,1) IS NULL AND array_length(v_group,1) IS NULL THEN
+        PERFORM public.analytics_assert_column(p_source, p_sort);
+      END IF;
+      v_sort_sql := format(' ORDER BY %I %s NULLS LAST',
+                           p_sort,
+                           CASE WHEN lower(COALESCE(p_dir,'desc')) = 'asc' THEN 'ASC' ELSE 'DESC' END);
+    END IF;
+  END IF;
+
+  -- 8.9 Page of rows.
+  EXECUTE format(
+    'SELECT COALESCE(jsonb_agg(t), ''[]''::jsonb) FROM (SELECT %s FROM public.%I%s%s%s LIMIT %s OFFSET %s) t',
+    array_to_string(v_select, ', '),
+    p_source,
+    v_where_sql,
+    CASE WHEN array_length(v_group, 1) > 0
+         THEN ' GROUP BY ' || array_to_string(v_group, ', ') ELSE '' END,
+    v_sort_sql,
+    v_limit,
+    v_offset
+  ) INTO v_rows;
+
+  -- 8.10 Row count for pagination. This must count what the MAIN query returns,
+  --      not what it reads: grouping ⇒ number of groups; aggregating with no
+  --      dimensions ⇒ exactly one row, however many rows fed it; otherwise the
+  --      underlying rows. Counting reads here made a 1-row KPI claim two pages.
+  IF array_length(v_group, 1) > 0 THEN
+    EXECUTE format(
+      'SELECT count(*) FROM (SELECT %s FROM public.%I%s GROUP BY %s) c',
+      array_to_string(v_group, ', '), p_source, v_where_sql, array_to_string(v_group, ', ')
+    ) INTO v_total;
+  ELSIF array_length(v_agg_only, 1) > 0 THEN
+    v_total := 1;
+  ELSE
+    EXECUTE format('SELECT count(*) FROM public.%I%s', p_source, v_where_sql) INTO v_total;
+  END IF;
+
+  -- 8.11 The summary: identical filters, identical measures, no group-by. This
+  --      is the KPI headline AND the report's total row — one number, one place.
+  IF array_length(v_agg_only, 1) > 0 THEN
+    EXECUTE format(
+      'SELECT to_jsonb(s) FROM (SELECT %s FROM public.%I%s) s',
+      array_to_string(v_agg_only, ', '),
+      p_source,
+      v_where_sql
+    ) INTO v_summary;
+  END IF;
+
+  RETURN jsonb_build_object(
+    'rows',    COALESCE(v_rows, '[]'::jsonb),
+    'total',   COALESCE(v_total, 0),
+    'summary', COALESCE(v_summary, '{}'::jsonb)
+  );
+END;
+$function$
+;

package/migrations/063_o_anexo_ja_registrado_recebe_os_bytes.sql

@@ -0,0 +1,303 @@
+-- ---------------------------------------------------------------------------
+-- 063_o_anexo_ja_registrado_recebe_os_bytes.sql — o motor de bytes aprende a
+-- ADOTAR um registro, em vez de sempre criar um.
+--
+-- A 054 desenhou o transporte de bytes para as duas espécies que existiam: o
+-- retrato do cadastro e a foto da batida. Nas duas, o registro em
+-- `public.documents` **nasce do próprio transporte** — não havia linha antes, e
+-- `attach_asset` cunha o id a partir do caminho de destino.
+--
+-- A 062 (o recibo da conta) quebra essa suposição, e quebra do jeito certo: o
+-- REGISTRO do anexo atravessa como LINHA, pelo `upsert_document`, com o id que
+-- ele tinha no V1 — e fica marcado `storage_provider = 'v1-pending'` esperando
+-- os bytes. Medido em 19/09/2026 no Pertinho do Céu: **1.192 anexos em 854
+-- contas**, todos registrados, nenhum com arquivo.
+--
+-- Oferecer um desses ao `attach_asset` de hoje criaria a SEGUNDA linha de
+-- `documents` para o mesmo anexo: o ledger não teria `target_id` (é a primeira
+-- oferta daquele objeto de storage), então ele cunharia um id novo. O anexo
+-- apareceria duas vezes na conta, um com bytes e outro sem, e o `v_person_files`
+-- da LGPD contaria dois arquivos onde há um.
+--
+-- ── O que muda ─────────────────────────────────────────────────────────────
+--
+-- Uma coluna no contrato do backlog: `document_id`. Preenchida, quer dizer "o
+-- registro já existe, é este — só ponha os bytes nele". Nula, é o que sempre
+-- foi: o transporte cria o registro.
+--
+-- É a diferença entre as duas origens de um arquivo no porte, e ela é real:
+--
+--   avatar, punch_photo   o V1 guarda o caminho DENTRO da linha da pessoa ou da
+--                         batida. Não há linha de arquivo para adotar.
+--   attachment            o V1 tem uma TABELA de anexos, e ela atravessa como
+--                         qualquer outra tabela, pelo de-para.
+--
+-- ── O bucket ───────────────────────────────────────────────────────────────
+--
+-- Privado. É comprovante de pagamento — boleto, nota, print de transferência —
+-- e a régua é a mesma da foto de ponto: o que basta um caminho para ver não
+-- devia ser um documento financeiro de uma empresa.
+--
+-- Idempotente e replay-safe.
+-- ---------------------------------------------------------------------------
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  O bucket
+-- ─────────────────────────────────────────────────────────────────────────
+
+INSERT INTO storage.buckets (id, name, public, file_size_limit, allowed_mime_types)
+VALUES ('attachments', 'attachments', false, 26214400, NULL)
+ON CONFLICT (id) DO UPDATE SET
+  public          = EXCLUDED.public,
+  file_size_limit = EXCLUDED.file_size_limit;
+
+DROP POLICY IF EXISTS core_attachments_read   ON storage.objects;
+DROP POLICY IF EXISTS core_attachments_insert ON storage.objects;
+DROP POLICY IF EXISTS core_attachments_update ON storage.objects;
+
+-- Sem `anon` e sem DELETE: comprovante de pagamento não se lê deslogado e não
+-- se apaga por clique. Remoção definitiva passa pelo `service_role`, que é ato
+-- deliberado — a mesma régua da foto de ponto (plugin-workforce 001).
+CREATE POLICY core_attachments_read ON storage.objects
+  FOR SELECT TO authenticated
+  USING (
+    bucket_id = 'attachments'
+    AND (storage.foldername(name))[1] IN (SELECT public.user_tenant_ids()::text)
+  );
+
+CREATE POLICY core_attachments_insert ON storage.objects
+  FOR INSERT TO authenticated
+  WITH CHECK (
+    bucket_id = 'attachments'
+    AND (storage.foldername(name))[1] IN (SELECT public.user_tenant_ids()::text)
+  );
+
+CREATE POLICY core_attachments_update ON storage.objects
+  FOR UPDATE TO authenticated
+  USING (
+    bucket_id = 'attachments'
+    AND (storage.foldername(name))[1] IN (SELECT public.user_tenant_ids()::text)
+  )
+  WITH CHECK (
+    bucket_id = 'attachments'
+    AND (storage.foldername(name))[1] IN (SELECT public.user_tenant_ids()::text)
+  );
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  O backlog ganha `document_id`
+--
+-- `asset_backlog` muda de forma, então é DROP e não REPLACE — o Postgres não
+-- troca o tipo de retorno de uma função no lugar.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE VIEW migration.v_asset_backlog_attachment AS
+SELECT d.tenant_id,
+       d.subject_type,
+       d.subject_id,
+       d.person_id,
+       d.storage_path AS source_path,
+       -- O bucket de anexos do V1 é público, mas a descida vai pela chave de
+       -- serviço do mesmo jeito: uma URL pública montada aqui dependeria do
+       -- host do V1, que tem DOIS (o do projeto e o domínio próprio) e nenhum
+       -- deles é coisa que o destino deva saber.
+       NULL::text     AS source_url,
+       -- Nomeado pelo REGISTRO, não pelo caminho de origem. O caminho do V1
+       -- carrega o uuid da fatura do V1 e um epoch; o do V2 é derivável do id
+       -- do documento, que é o que a tela já tem na mão.
+       d.tenant_id::text || '/' || d.id::text
+         || lower(coalesce(substring(coalesce(d.file_name, '') from '\.[A-Za-z0-9]{2,5}$'), '')) AS target_path,
+       coalesce(nullif(btrim(d.title), ''), d.file_name) AS title,
+       d.id           AS document_id
+  FROM public.documents d
+ -- `v1-pending` é a marca que a 062 deixa: o registro chegou, o arquivo não.
+ -- Escrever os bytes troca o provider e apaga a linha desta lista.
+ WHERE d.storage_provider = 'v1-pending'
+   AND coalesce(btrim(d.storage_path), '') <> '';
+
+COMMENT ON VIEW migration.v_asset_backlog_attachment IS
+  'Anexos cujo REGISTRO atravessou (062) e cujo arquivo ainda está no V1 (063). A condição é o próprio `storage_provider`: gravar os bytes apaga a linha daqui.';
+
+DROP FUNCTION IF EXISTS migration.asset_backlog(uuid, text);
+
+CREATE FUNCTION migration.asset_backlog(p_tenant uuid, p_kind text DEFAULT NULL)
+RETURNS TABLE (
+  kind text, source_bucket text, target_bucket text,
+  tenant_id uuid, subject_type text, subject_id uuid, person_id uuid,
+  source_path text, source_url text, target_path text, title text,
+  -- Preenchido = o registro já existe e deve ser ADOTADO. Nulo = o transporte
+  -- cria o registro, que é o caso do avatar e da foto de ponto.
+  document_id uuid)
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE k migration.asset_kinds%ROWTYPE;
+BEGIN
+  FOR k IN SELECT * FROM migration.asset_kinds a
+            WHERE p_kind IS NULL OR a.kind = p_kind
+            ORDER BY a.kind
+  LOOP
+    -- Espécie declarada cuja view ainda não existe é o caso do plugin
+    -- desinstalado, não um erro.
+    IF to_regclass('migration.' || quote_ident(k.backlog_view)) IS NULL THEN
+      CONTINUE;
+    END IF;
+    -- `document_id` é opcional na view: as de antes da 063 não a têm, e
+    -- reemitir as duas para acrescentar uma coluna nula seria churn. O
+    -- `to_jsonb(v)` lê a linha inteira e devolve NULL para a chave ausente.
+    RETURN QUERY EXECUTE format(
+      'SELECT %L::text, %L::text, %L::text, v.tenant_id, v.subject_type, v.subject_id,
+              v.person_id, v.source_path, v.source_url, v.target_path, v.title,
+              (to_jsonb(v) ->> ''document_id'')::uuid
+         FROM migration.%I v
+        WHERE v.tenant_id = $1
+          AND coalesce(btrim(v.source_path), '''') <> ''''',
+      k.kind, k.source_bucket, k.target_bucket, k.backlog_view)
+    USING p_tenant;
+  END LOOP;
+END $$;
+
+COMMENT ON FUNCTION migration.asset_backlog(uuid, text) IS
+  'O que falta de BYTES neste tenant, por espécie (054, 063). `document_id` preenchido = o registro já existe e deve ser adotado em vez de criado.';
+
+GRANT EXECUTE ON FUNCTION migration.asset_backlog(uuid, text) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §3  `attach_asset` adota o registro quando ele vem nomeado
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION migration._attach_asset_impl(
+  p_batch uuid, p_kind text, p_source_path text, p_row jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  b migration.batches%ROWTYPE;
+  k migration.asset_kinds%ROWTYPE;
+  l migration.ledger%ROWTYPE;
+  v_source_table text;
+  v_source_uuid  uuid;
+  v_checksum text := p_row ->> 'checksum';
+  v_doc uuid;
+  v_person uuid := nullif(p_row ->> 'person_id', '')::uuid;
+  v_adotado uuid := nullif(p_row ->> 'document_id', '')::uuid;
+BEGIN
+  SELECT * INTO b FROM migration.batches WHERE id = p_batch;
+  IF NOT FOUND THEN RAISE EXCEPTION 'attach_asset: lote % desconhecido', p_batch USING ERRCODE = 'P0002'; END IF;
+  IF b.status <> 'running' THEN
+    RAISE EXCEPTION 'attach_asset: o lote % está %  (só um lote em execução aceita arquivo)', p_batch, b.status USING ERRCODE = '55000';
+  END IF;
+  PERFORM migration._assert_fence(b.tenant_id);
+
+  SELECT * INTO k FROM migration.asset_kinds WHERE kind = p_kind;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'attach_asset: espécie % não está em migration.asset_kinds', p_kind USING ERRCODE = '22023';
+  END IF;
+  IF v_checksum IS NULL OR p_row ->> 'target_path' IS NULL THEN
+    RAISE EXCEPTION 'attach_asset: preciso de checksum e target_path' USING ERRCODE = '22023';
+  END IF;
+
+  v_source_table := 'storage:' || k.source_bucket;
+  v_source_uuid  := md5(v_source_table || ':' || p_source_path)::uuid;
+
+  SELECT * INTO l FROM migration.ledger
+   WHERE source_project = b.source_project AND source_table = v_source_table
+     AND source_uuid = v_source_uuid AND coalesce(target_table, '') = 'public.documents'
+   FOR UPDATE;
+  IF NOT FOUND THEN
+    INSERT INTO migration.ledger (source_project, source_table, source_uuid, tenant_id,
+                                  target_table, checksum, cursor, batch_id, status)
+    VALUES (b.source_project, v_source_table, v_source_uuid, b.tenant_id,
+            'public.documents', v_checksum, p_source_path, p_batch, 'pending')
+    RETURNING * INTO l;
+  ELSIF l.tenant_id <> b.tenant_id THEN
+    RETURN migration._quarantine(l.id, p_batch, 'tenant',
+      format('o objeto %s já é do tenant %s; este lote migra o %s', p_source_path, l.tenant_id, b.tenant_id), p_row);
+  ELSIF l.status = 'migrated' AND l.checksum = v_checksum THEN
+    PERFORM migration._count(p_batch, 'skipped');
+    RETURN jsonb_build_object('status', 'skipped', 'reason', 'bytes iguais',
+                              'target_table', 'public.documents', 'target_id', l.target_id, 'ledger_id', l.id);
+  END IF;
+
+  -- A ordem é a decisão da 063. O registro ADOTADO vem primeiro: quando o
+  -- backlog nomeia um `document_id`, aquela linha é o anexo, e cunhar outra
+  -- deixaria o mesmo arquivo duas vezes na conta — um com bytes, outro sem.
+  v_doc := coalesce(v_adotado, l.target_id, md5('document:' || p_kind || ':' || (p_row ->> 'target_path'))::uuid);
+
+  IF v_adotado IS NOT NULL AND NOT EXISTS (
+       SELECT 1 FROM public.documents d WHERE d.id = v_adotado AND d.tenant_id = b.tenant_id) THEN
+    RETURN migration._quarantine(l.id, p_batch, 'fk',
+      format('o registro %s não existe neste tenant — o backlog está apontando para um documento que sumiu', v_adotado), p_row);
+  END IF;
+
+  INSERT INTO public.documents (
+    id, tenant_id, kind, person_id, subject_type, subject_id, title, status,
+    file_url, file_name, file_size, mime_type,
+    storage_provider, storage_bucket, storage_path, checksum, metadata)
+  VALUES (
+    v_doc, b.tenant_id, p_kind, v_person,
+    p_row ->> 'subject_type', nullif(p_row ->> 'subject_id', '')::uuid,
+    p_row ->> 'title', 'active',
+    p_row ->> 'public_url', p_row ->> 'file_name',
+    nullif(p_row ->> 'file_size', '')::integer, p_row ->> 'mime_type',
+    'supabase', k.target_bucket, p_row ->> 'target_path', v_checksum,
+    jsonb_build_object('migration', jsonb_build_object(
+      'source_project', b.source_project, 'source_bucket', k.source_bucket,
+      'source_path', p_source_path, 'batch_id', p_batch)))
+  ON CONFLICT (id) DO UPDATE SET
+    person_id        = coalesce(EXCLUDED.person_id, public.documents.person_id),
+    -- Num registro adotado, quem sabe o sujeito e o nome é a linha que já está
+    -- lá: ela veio do de-para. O que o transporte tem a dizer é onde os bytes
+    -- foram parar.
+    subject_type     = coalesce(public.documents.subject_type, EXCLUDED.subject_type),
+    subject_id       = coalesce(public.documents.subject_id, EXCLUDED.subject_id),
+    title            = coalesce(public.documents.title, EXCLUDED.title),
+    file_url         = EXCLUDED.file_url,
+    file_name        = coalesce(public.documents.file_name, EXCLUDED.file_name),
+    file_size        = EXCLUDED.file_size,
+    mime_type        = coalesce(EXCLUDED.mime_type, public.documents.mime_type),
+    storage_provider = EXCLUDED.storage_provider,
+    storage_bucket   = EXCLUDED.storage_bucket,
+    storage_path     = EXCLUDED.storage_path,
+    checksum         = EXCLUDED.checksum,
+    is_active        = true,
+    metadata         = migration._merge_meta(public.documents.metadata, EXCLUDED.metadata),
+    updated_at       = now();
+
+  IF k.pointer_fn IS NOT NULL THEN
+    EXECUTE format('SELECT %s($1, $2, $3)', k.pointer_fn)
+      USING b.tenant_id, v_doc, p_row || jsonb_build_object('bucket', k.target_bucket);
+  END IF;
+
+  UPDATE migration.ledger
+     SET status = 'migrated', target_id = v_doc, checksum = v_checksum,
+         cursor = p_source_path, batch_id = p_batch, reason = NULL
+   WHERE id = l.id;
+  PERFORM migration._count(p_batch, 'migrated');
+
+  RETURN jsonb_build_object('status', 'migrated', 'target_table', 'public.documents',
+                            'target_id', v_doc, 'ledger_id', l.id);
+END $$;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §4  A espécie
+--
+-- Sem `pointer_fn`: o ponteiro do anexo é o próprio `public.documents`, e o
+-- `attach_asset` já grava bucket, caminho e provider nele. Não há segunda
+-- tabela para avisar — é o caso que a 054 previu quando deixou a coluna
+-- anulável.
+-- ─────────────────────────────────────────────────────────────────────────
+
+SELECT migration.register_asset_kind(
+  'attachment', 'bill-attachments', 'attachments',
+  'v_asset_backlog_attachment', NULL,
+  'O recibo da conta. O REGISTRO atravessa como linha pelo de-para (062) e fica com storage_provider = ''v1-pending''; aqui vêm os bytes, e o registro é ADOTADO em vez de recriado.');
+
+
+-- ── quem pode executar ────────────────────────────────────────────────────
+--
+-- Função nova nasce executável por PUBLIC, e `anon`/`authenticated` herdam
+-- dali. Estas são de PORTE: SECURITY DEFINER, escrevem dados de qualquer
+-- inquilino. Só o service_role, que é quem roda a onda.
+REVOKE ALL ON FUNCTION migration.asset_backlog(uuid, text) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION migration.asset_backlog(uuid, text) TO service_role;
+REVOKE ALL ON FUNCTION migration._attach_asset_impl(uuid, text, text, jsonb) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION migration._attach_asset_impl(uuid, text, text, jsonb) TO service_role;