@fayz-ai/db 0.14.0 → 0.16.0

package/migrations/054_o_arquivo_migrado_ganha_bytes.sql

@@ -0,0 +1,439 @@
+-- ---------------------------------------------------------------------------
+-- 054_o_arquivo_migrado_ganha_bytes.sql — o porte passa a carregar a imagem, e
+-- não só o caminho dela.
+--
+-- A 152 dividiu o arquivo em duas metades: o REGISTRO é do base
+-- (`public.documents` — de quem é, que espécie é, quem pode ver) e os BYTES são
+-- de um serviço de storage, com a linha apontando para eles. A metade do
+-- registro ficou pronta. A dos bytes, no porte V1 → V2, nunca existiu.
+--
+-- ── O sintoma, medido em 18/09/2026 ─────────────────────────────────────────
+--
+-- No tenant Pertinho do Céu, 1.320 das 1.361 batidas de ponto chegaram ao V2
+-- com `evidence.photo_path` preenchido — `8/2026-07-05/professional-15-…jpg`.
+-- Esse caminho é de um bucket PRIVADO de OUTRO projeto Supabase, o do V1.
+-- Nenhuma dessas 1.320 imagens é alcançável daqui, e todas desaparecem no dia
+-- em que o V1 sair do ar.
+--
+-- O porte transportou a prova por referência e deixou a prova para trás. Uma
+-- batida contestada tem hora, GPS e score facial, e não tem a cara de quem
+-- bateu — que é o único dos quatro que uma pessoa reconhece.
+--
+-- A mesma coisa vale para o cadastro: `people.avatar_url` chegou com a URL
+-- pública do bucket `professional-avatars` do V1 (63 pessoas no mesmo tenant).
+-- Hoje ela até abre, porque o V1 está de pé. É um empréstimo com data marcada.
+--
+-- ── A decisão: o transporte é de fora, o registro e o ponteiro são daqui ────
+--
+-- Mover bytes entre dois projetos é rede, não SQL, e é o fayz-etl que faz
+-- (`fayz_etl/blobs.py`). O que ESTE arquivo dá a ele é a mesma coisa que o resto
+-- do schema `migration` dá ao `upsert_row`:
+--
+--   asset_kinds       o de-para dos buckets: que espécie sai de onde e vai para
+--                     onde, e quem reescreve o ponteiro depois
+--   asset_backlog()   o que falta atravessar, perguntado ao DESTINO — quem sabe
+--                     o que está faltando é quem guarda o que já chegou
+--   attach_asset()    registra em public.documents, reescreve o ponteiro e
+--                     carimba o ledger; idempotente pelo checksum dos bytes
+--
+-- O fayz-etl não escolhe bucket, não monta caminho e não sabe o que é um
+-- ponteiro de avatar. Ele lê o backlog, baixa, sobe e oferece — a mesma divisão
+-- que fez o porte de linhas caber em 900 linhas de Python.
+--
+-- ── Por que o backlog é uma VIEW por espécie, e não uma coluna de SQL ───────
+--
+-- Cada espécie tem uma pergunta diferente para "o que falta": o avatar é a
+-- pessoa cujo `avatar_url` AINDA aponta para o V1; a foto de batida é a linha
+-- cuja `evidence` tem `photo_path` e não tem `photo`. As duas se apagam sozinhas
+-- quando o ponteiro é reescrito — o backlog não precisa de estado próprio, e não
+-- há segunda lista para ficar desatualizada.
+--
+-- Uma view também é verificável: `check-canonical-schema` a enxerga, e um
+-- plugin que registre um nome de view que não existe quebra na aplicação, não
+-- numa rodada às 4h da manhã.
+--
+-- Idempotente e replay-safe.
+-- ---------------------------------------------------------------------------
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  O bucket dos avatares
+--
+-- Público, e é o que o app já assume: `packages/admin` chama
+-- `storage.from('avatars').getPublicUrl(...)` em quatro lugares. O bucket nunca
+-- foi criado neste cluster — a troca de foto no cadastro está quebrada desde
+-- sempre, e ninguém viu porque o erro morre num toast.
+-- ─────────────────────────────────────────────────────────────────────────
+
+INSERT INTO storage.buckets (id, name, public, file_size_limit, allowed_mime_types)
+VALUES ('avatars', 'avatars', true, 5242880,
+        ARRAY['image/jpeg', 'image/png', 'image/webp', 'image/heic', 'image/heif', 'image/gif'])
+ON CONFLICT (id) DO UPDATE SET
+  public             = EXCLUDED.public,
+  file_size_limit    = EXCLUDED.file_size_limit,
+  allowed_mime_types = EXCLUDED.allowed_mime_types;
+
+DROP POLICY IF EXISTS core_avatars_read   ON storage.objects;
+DROP POLICY IF EXISTS core_avatars_insert ON storage.objects;
+DROP POLICY IF EXISTS core_avatars_update ON storage.objects;
+DROP POLICY IF EXISTS core_avatars_delete ON storage.objects;
+
+CREATE POLICY core_avatars_read ON storage.objects
+  FOR SELECT TO anon, authenticated
+  USING (bucket_id = 'avatars');
+
+-- Duas formas de caminho convivem no mesmo bucket, e é de propósito:
+--
+--   avatars/<auth-uid>.<ext>            a foto que a PESSOA LOGADA troca de si
+--                                       mesma (packages/admin). Não é de tenant
+--                                       nenhum: a conta atravessa workspaces.
+--   <tenant_id>/people/<person_id>.<ext>  a foto de um CADASTRO, que é do tenant
+--                                       e segue o escopo de pasta que o resto
+--                                       da plataforma usa.
+CREATE POLICY core_avatars_insert ON storage.objects
+  FOR INSERT TO authenticated
+  WITH CHECK (
+    bucket_id = 'avatars'
+    AND ((storage.foldername(name))[1] = 'avatars'
+      OR (storage.foldername(name))[1] IN (SELECT public.user_tenant_ids()::text))
+  );
+
+CREATE POLICY core_avatars_update ON storage.objects
+  FOR UPDATE TO authenticated
+  USING (
+    bucket_id = 'avatars'
+    AND ((storage.foldername(name))[1] = 'avatars'
+      OR (storage.foldername(name))[1] IN (SELECT public.user_tenant_ids()::text))
+  )
+  WITH CHECK (
+    bucket_id = 'avatars'
+    AND ((storage.foldername(name))[1] = 'avatars'
+      OR (storage.foldername(name))[1] IN (SELECT public.user_tenant_ids()::text))
+  );
+
+CREATE POLICY core_avatars_delete ON storage.objects
+  FOR DELETE TO authenticated
+  USING (
+    bucket_id = 'avatars'
+    AND ((storage.foldername(name))[1] = 'avatars'
+      OR (storage.foldername(name))[1] IN (SELECT public.user_tenant_ids()::text))
+  );
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  A espécie "retrato de uma pessoa"
+-- ─────────────────────────────────────────────────────────────────────────
+
+-- `active` declarado, e não inventado no INSERT: o registro de espécies existe
+-- para que o vocabulário de estado de cada arquivo esteja escrito em algum lugar.
+-- Um retrato não tem rascunho nem aprovação — ele vale ou foi substituído.
+SELECT public.register_kind('document', 'avatar', 'base', ARRAY['active', 'archived'], NULL,
+  'O retrato de uma pessoa no cadastro — o que a tela mostra ao lado do nome');
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §3  O de-para dos buckets
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS migration.asset_kinds (
+  kind          text PRIMARY KEY REFERENCES public.document_kinds(kind),
+  -- O bucket na ORIGEM. Quando a origem serve o objeto por URL pública, a view
+  -- de backlog devolve `source_url` e este campo é só documentação.
+  source_bucket text NOT NULL,
+  target_bucket text NOT NULL,
+  -- View em `migration` com o contrato de colunas do §4. O nome, e não a
+  -- definição: cada plugin declara a sua, e a sua pergunta é diferente.
+  backlog_view  text NOT NULL,
+  -- `(p_tenant uuid, p_document uuid, p_row jsonb) RETURNS void`. NULL é uma
+  -- resposta legítima: há espécie que só precisa estar registrada em
+  -- public.documents, sem ponteiro em outra tabela para reescrever.
+  pointer_fn    text,
+  -- Obrigatório. Espécie sem motivo escrito vira folclore em seis meses, e esta
+  -- tabela é lida por quem está depurando uma rodada que não trouxe nada.
+  notes         text NOT NULL,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE migration.asset_kinds IS
+  'O de-para dos BYTES (054): de que bucket da origem sai cada espécie de arquivo, para que bucket do destino vai, onde está a lista do que falta e quem reescreve o ponteiro. É o que a allowlist é para as linhas.';
+
+DROP TRIGGER IF EXISTS asset_kinds_updated_at ON migration.asset_kinds;
+CREATE TRIGGER asset_kinds_updated_at BEFORE UPDATE ON migration.asset_kinds
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+CREATE OR REPLACE FUNCTION migration.register_asset_kind(
+  p_kind text, p_source_bucket text, p_target_bucket text,
+  p_backlog_view text, p_pointer_fn text, p_notes text)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+BEGIN
+  INSERT INTO migration.asset_kinds (kind, source_bucket, target_bucket, backlog_view, pointer_fn, notes)
+  VALUES (p_kind, p_source_bucket, p_target_bucket, p_backlog_view, p_pointer_fn, p_notes)
+  ON CONFLICT (kind) DO UPDATE SET
+    source_bucket = EXCLUDED.source_bucket,
+    target_bucket = EXCLUDED.target_bucket,
+    backlog_view  = EXCLUDED.backlog_view,
+    pointer_fn    = EXCLUDED.pointer_fn,
+    notes         = EXCLUDED.notes;
+END $$;
+
+COMMENT ON FUNCTION migration.register_asset_kind(text, text, text, text, text, text) IS
+  'Como um plugin declara que uma espécie de arquivo dele tem bytes para transportar (054). Idempotente — reaplicar a migration reescreve a linha.';
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §4  O que falta atravessar
+--
+-- Contrato de colunas que toda `backlog_view` precisa devolver:
+--
+--   tenant_id     uuid    de quem é
+--   subject_type  text    'person', 'time_entry', 'invoice'…
+--   subject_id    uuid    a linha do destino que aponta para o arquivo
+--   person_id     uuid    a pessoa, quando há uma (é a pergunta da LGPD)
+--   source_path   text    o objeto DENTRO do bucket de origem
+--   source_url    text    URL direta, quando a origem serve o objeto em público;
+--                         NULL = baixe pelo bucket com a chave de serviço
+--   target_path   text    o objeto no bucket de destino. Determinístico, sempre:
+--                         rodar duas vezes sobrescreve, não duplica
+--   title         text    o que uma pessoa lê numa lista de arquivos
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE VIEW migration.v_asset_backlog_avatar AS
+SELECT p.tenant_id,
+       'person'::text AS subject_type,
+       p.id           AS subject_id,
+       p.id           AS person_id,
+       -- Os dois hosts do V1 servem o mesmo bucket: o projeto
+       -- (xzihdmcyoyrjndpvlxdj.supabase.co) e o domínio próprio
+       -- (api.ymaia.com). O recorte é pelo caminho, que é igual nos dois.
+       regexp_replace(p.avatar_url, '^.*/storage/v1/object/public/professional-avatars/', '') AS source_path,
+       p.avatar_url   AS source_url,
+       p.tenant_id::text || '/people/' || p.id::text
+         || lower(coalesce(substring(p.avatar_url from '\.[A-Za-z0-9]{2,4}$'), '.jpg')) AS target_path,
+       p.name         AS title
+  FROM public.people p
+ -- O próprio ponteiro é o backlog: enquanto a URL apontar para o bucket do V1,
+ -- os bytes não atravessaram. Reescrevê-la tira a linha daqui, sem lista à
+ -- parte para ficar desatualizada.
+ WHERE p.avatar_url ~ '/storage/v1/object/public/professional-avatars/';
+
+COMMENT ON VIEW migration.v_asset_backlog_avatar IS
+  'Pessoas cujo retrato ainda mora no bucket do V1 (054). A condição É o ponteiro: reescrevê-lo apaga a linha desta lista.';
+
+-- DROP antes do CREATE, e não só REPLACE: `CREATE OR REPLACE` recusa mudar a
+-- FORMA do retorno ("cannot change return type of existing function"), e uma
+-- migration posterior já mudou a desta — a 063, que acrescentou colunas ao
+-- backlog. Na segunda passada do chain este arquivo roda de novo e encontra a
+-- forma nova; sem o drop, ele falha ali e o replay inteiro para.
+--
+-- Replay-safe não é propriedade de um arquivo sozinho: é propriedade dele
+-- DEPOIS de tudo o que veio em seguida.
+DROP FUNCTION IF EXISTS migration.asset_backlog(uuid, text);
+CREATE OR REPLACE 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)
+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: o cluster monta por plugin, e o porte de um
+    -- cliente sem `workforce` não pode quebrar por causa de foto de ponto.
+    IF to_regclass('migration.' || quote_ident(k.backlog_view)) IS NULL THEN
+      CONTINUE;
+    END IF;
+    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
+         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). Perguntado ao destino de propósito: quem sabe o que está faltando é quem guarda o que já chegou.';
+
+GRANT EXECUTE ON FUNCTION migration.asset_backlog(uuid, text) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §5  O ponteiro do avatar
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION migration._point_avatar(p_tenant uuid, p_document uuid, p_row jsonb)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE v_person uuid := (p_row ->> 'subject_id')::uuid;
+        v_url    text  := p_row ->> 'public_url';
+BEGIN
+  IF v_person IS NULL OR v_url IS NULL THEN
+    RAISE EXCEPTION '_point_avatar: preciso de subject_id e public_url' USING ERRCODE = '22023';
+  END IF;
+  -- A URL do V1 vira histórico em vez de sumir. É o que permite conferir, um
+  -- ano depois, que o retrato que está no V2 é o retrato que estava no V1 —
+  -- sem isso a única prova da procedência é o log de uma rodada.
+  UPDATE public.people
+     SET avatar_url = v_url,
+         metadata   = migration._deep_set(coalesce(metadata, '{}'::jsonb),
+                        ARRAY['migration', 'v1_avatar_url'], to_jsonb(avatar_url)),
+         updated_at = now()
+   WHERE id = v_person AND tenant_id = p_tenant;
+END $$;
+
+SELECT migration.register_asset_kind(
+  'avatar', 'professional-avatars', 'avatars',
+  'v_asset_backlog_avatar', 'migration._point_avatar',
+  'O retrato do cadastro. A origem serve por URL pública, então o backlog devolve source_url e o transporte nem precisa de chave na origem.');
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §6  attach_asset — registra, aponta, carimba
+--
+-- A forma é a do `upsert_row` de propósito: mesma casca que liga
+-- `migration.writer`, mesma cerca, mesmo ledger, mesmo jsonb de volta. Quem
+-- souber depurar uma rodada de linhas sabe depurar uma de bytes.
+--
+-- O checksum do ledger é dos BYTES, não da linha. É o que faz a segunda rodada
+-- devolver `skipped` para 1.320 fotos sem baixar nenhuma delas de novo.
+-- ─────────────────────────────────────────────────────────────────────────
+
+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;
+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;
+
+  -- `storage:<bucket>` e não o nome de uma tabela: a origem de um byte é um
+  -- bucket, e o prefixo deixa isso explícito para quem lê o ledger depois.
+  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;
+
+  -- O id do registro é derivado do caminho de DESTINO, que é determinístico.
+  -- Rerun sobrescreve a mesma linha; não há segunda cópia do mesmo arquivo.
+  v_doc := coalesce(l.target_id, md5('document:' || p_kind || ':' || (p_row ->> 'target_path'))::uuid);
+
+  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),
+    subject_type     = EXCLUDED.subject_type,
+    subject_id       = EXCLUDED.subject_id,
+    title            = coalesce(EXCLUDED.title, public.documents.title),
+    file_url         = EXCLUDED.file_url,
+    file_name        = EXCLUDED.file_name,
+    file_size        = EXCLUDED.file_size,
+    mime_type        = EXCLUDED.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 $$;
+
+CREATE OR REPLACE FUNCTION migration.attach_asset(
+  p_batch uuid, p_kind text, p_source_path text, p_row jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE v jsonb;
+BEGIN
+  IF p_row IS NULL OR jsonb_typeof(p_row) <> 'object' THEN
+    RAISE EXCEPTION 'attach_asset: p_row precisa ser um objeto JSON' USING ERRCODE = '22023';
+  END IF;
+  -- `migration.writer = on` é o que abre as travas de append-only do destino —
+  -- a batida recusa UPDATE por trigger, e apontar a foto dela é um UPDATE.
+  PERFORM set_config('migration.writer', 'on', true);
+  PERFORM set_config('migration.batch', p_batch::text, true);
+  BEGIN
+    v := migration._attach_asset_impl(p_batch, p_kind, p_source_path, p_row);
+  EXCEPTION WHEN OTHERS THEN
+    PERFORM set_config('migration.writer', 'off', true);
+    PERFORM set_config('migration.batch', '', true);
+    RAISE;
+  END;
+  PERFORM set_config('migration.writer', 'off', true);
+  PERFORM set_config('migration.batch', '', true);
+  RETURN v;
+END $$;
+
+COMMENT ON FUNCTION migration.attach_asset(uuid, text, text, jsonb) IS
+  'Um arquivo que atravessou: registra em public.documents, reescreve o ponteiro da espécie e carimba o ledger (054). O checksum é dos BYTES — é o que faz a segunda rodada devolver skipped sem baixar nada.';
+
+GRANT EXECUTE ON FUNCTION migration.attach_asset(uuid, text, text, jsonb) TO service_role;