@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/standards/ai-agents/media-pipeline.md

@@ -0,0 +1,352 @@
+# Media Pipeline — job, revisão humana, proveniência e marcação
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (load when relevant)
+> **Keywords:** media pipeline, media job, geração de mídia, revisão humana, C2PA, SynthID, AI Act, idempotência de mídia, teto de custo, marcação de IA
+> **Read by Claude in:** plan e implement (sempre que a feature gerar imagem ou vídeo)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + OpenAI 2.13.0 + Google.GenAI 1.21.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Media/` — a máquina de estados (`MediaJob`), a revisão humana (`MediaReview`), a marcação exigida na publicação (`MediaDisclosure` + `MediaJob.Publish`), as duas chaves (`MediaIdempotencyKey` × `MediaHash`), o storage por conteúdo (`MediaStore`) e a acessibilidade `internal` de `IMediaProvider` compilam e são exercitados por teste. Preço, data de desligamento, C2PA/SynthID e o texto legal do AI Act são **verificação documental** contra as páginas de §Como re-verificar este standard. Last-verified: 2026-09-08.
+
+---
+
+**Fronteira, primeiro.** `ai-agents/durable-workflows-hitl.md` cobre HITL e checkpoint **dentro de
+um Workflow MAF** — `RequestPort`, `RequestInfoEvent`, `ICheckpointStore`. Este standard é a outra
+coisa: um **pipeline de domínio**, cujo mecanismo de job é `BackgroundService`/Channels ou
+Hangfire/Quartz com storage persistido. O wiring de job (enqueue, retry, `IDbContextFactory`,
+dashboard) já é standard e **não se repete aqui**:
+`backend/integrations/hangfire/hangfire-jobs.md`. Use `RequestPort` só quando o passo humano é, de
+fato, um nó de um grafo de agente — o que quase nunca é o caso de aprovar uma foto de catálogo.
+
+O que este standard acrescenta ao mecanismo de job é o que o job **não sabe**: quais estados
+existem, quem pode aprovar, o que é persistido, o que é marcado e quanto pode custar.
+
+Imagem: `ai-agents/modalities-image-gen.md`. Vídeo: `ai-agents/media-video.md`.
+
+---
+
+## A regra dura
+
+> **Nunca gere mídia dentro de um turno de conversa.** Nem em WhatsApp, nem em chat, nem em webhook
+> síncrono. O turno **enfileira e confirma**; a mídia volta depois, revisada.
+
+Três números sustentam a regra, e nenhum deles é opinião:
+
+| Fato | Consequência dentro do turno |
+|---|---|
+| Imagem: latência documentada de **até 2 minutos** para prompt complexo | O turno estoura antes da resposta |
+| Vídeo: **11 s a 6 min**, assíncrono por desenho em todo provedor | Não existe caminho síncrono para tentar |
+| Custo **por chamada**, sem teto natural | Um usuário curioso vira uma fatura |
+| **Zero revisão possível** dentro do turno | Claim visual errado sai direto para o cliente |
+
+O quarto é o que não tem contorno técnico. Latência se resolve com paciência e custo com orçamento;
+"ninguém olhou antes de publicar" não se resolve com nada.
+
+> **De onde vêm os dois números de latência.** "Até 2 minutos" é a frase do guia de geração de imagem
+> da OpenAI (`https://developers.openai.com/api/docs/guides/image-generation`); "11 s a 6 min" é a
+> faixa da documentação do Veo (`https://ai.google.dev/gemini-api/docs/veo`). Ambas consultadas em
+> **2026-09-07**, e ambas na lista de §Como re-verificar este standard. **Nenhum dos dois foi medido
+> por esta casa** — gerar mídia para cronometrar custaria dinheiro, e um número medido uma vez numa
+> região não vale como SLA.
+
+### Como a regra é presa
+
+**Prosa não prende regra.** O que prende é a forma da API:
+
+- O tipo que **produz bytes** (`IMediaProvider` e as implementações de provedor) é `internal` ao
+  assembly do kit, com `InternalsVisibleTo` liberando apenas os testes. Um handler de mensagem no
+  projeto consumidor **não consegue nomear** esse tipo — o código não compila.
+- A única superfície pública é `IMediaGenerator.EnqueueAsync`, que devolve um **id de job** e nunca
+  bytes. `GetAsync` devolve o job, com o estado dele.
+- O worker que chama o provedor também é `internal`. Ele é montado por uma **raiz de composição**
+  (`MorphMedia.Create(options)`, no exemplar), que devolve as duas interfaces públicas —
+  `IMediaGenerator` e `IMediaJobRunner` — e nenhuma forma de alcançar o provider. O projeto registra
+  o resultado no seu contêiner numa linha; a montagem **não** é uma extensão de `IServiceCollection`,
+  porque isso obrigaria o kit a referenciar o pacote de DI, e o exemplar deste repositório escreve o
+  porquê no próprio arquivo. A propriedade que importa é a mesma nos dois desenhos: **não existe
+  caminho público até o tipo que produz bytes.**
+
+É a diferença entre "o standard diz para não fazer" e "o compilador recusa". O exemplar está em
+`templates/dotnet/ai-kit/src/Morph.AiKit/Media/`, e a acessibilidade é asserida por reflexão num
+teste — porque uma regra que ninguém viu falhar pode ser a regra errada.
+
+### O que o tipo prende, e o que ele não prende
+
+Ser exato aqui vale mais que ser tranquilizador, porque é o exato que sobrevive a uma revisão.
+
+**Prende:** um handler não consegue **obter bytes** (a superfície pública devolve id de job) nem
+**nomear** o tipo que os produz (`internal` — o código não compila). Nenhuma quantidade de pressa
+contorna isso, e a acessibilidade é asserida por reflexão num teste.
+
+**Não prende:** `IMediaJobRunner.RunAsync` é **público** — precisa ser, porque é o
+`BackgroundService`/Hangfire do projeto que o dispara. Um handler pode escrever
+`await runner.RunAsync(id)` e, com isso, **aguardar a chamada paga dentro do turno**. Ele não vê os
+bytes, mas paga a latência: os mesmos até 2 min em imagem, 11 s a 6 min em vídeo.
+
+Ou seja: o tipo fecha **"gere estes bytes agora"** e deixa aberto **"rode este job agora"**. Fechar
+o segundo também exigiria esconder o gatilho de quem precisa dele, e o remédio seria pior. A leitura
+no seu projeto é literal: **um `await` num runner dentro de um handler de mensagem é o defeito**,
+mesmo compilando — e é isso que a revisão de código procura, porque o compilador não vai procurar
+por ela.
+
+---
+
+## A máquina de estados
+
+```
+Pending ──▶ Generating ──▶ Generated ──┬──▶ Approved ──▶ Published
+   │            │                      ├──▶ Rejected
+   └────────────┴──▶ Failed            └──▶ RejectedByPolicy
+```
+
+| Estado | Significa | Retryable? |
+|---|---|---|
+| `Pending` | Pedido aceito, nada gasto ainda | — |
+| `Generating` | Chamada paga em voo (ou tarefa remota em polling) | — |
+| `Generated` | Bytes existem no **seu** storage | — |
+| `Approved` | Humano aprovou. **Única** porta para `Published` | — |
+| `Rejected` | Humano recusou | não |
+| `RejectedByPolicy` | **Bloqueio de moderação do provedor** | **não** |
+| `Published` | Publicado, com a marcação **registrada junto** — ver a terceira porta abaixo | — |
+| `Failed` | Erro técnico (429, 5xx, timeout, download quebrado) | **sim** |
+
+**`RejectedByPolicy` não é `Failed`, e a distinção é dinheiro.** Um bloqueio de moderação é uma
+resposta definitiva: retentá-lo gasta para receber o mesmo "não" — e nos provedores que cobram o
+bloqueio, gasta duas vezes. Modelar bloqueio como erro técnico é como um retry loop vira uma fatura.
+
+**`Approve(reviewer)` é a única transição para `Approved`**, e `Publish()` devolve falha a partir de
+qualquer estado que não seja `Approved`. É assim que "há revisão humana" deixa de ser uma frase no
+README e vira um caminho que o código não tem.
+
+**A publicação tem três portas, e não uma.** No exemplar, a assinatura é
+`Publish(MediaDisclosure? disclosure, DateTimeOffset publishedAt)`, e ela recusa:
+
+1. **estado** diferente de `Approved` — inclusive `Generated`, que é o atalho que alguém sempre quer;
+2. **finalidade não publicável** — `Draft` se declarava "nunca publicável" num comentário que nada
+   cobrava;
+3. **marcação ausente** quando a finalidade a exige (`RequiresDisclosure()`: catálogo e marketing).
+
+A ordem importa e é testada: um job não aprovado reclama da revisão humana, **não** da marcação —
+mandar consertar o rótulo de algo que ninguém revisou manda consertar a coisa errada.
+
+---
+
+## As duas chaves de idempotência
+
+Duas chaves distintas, e confundi-las é o defeito caro:
+
+| Chave | Fórmula | O que dedupe |
+|---|---|---|
+| **De pedido** | `sha256(provider + model + prompt normalizado + sha256 de cada referência + opções)` | A **chamada paga** |
+| **De conteúdo** | `sha256(bytes)` | O **storage** |
+
+A chave **de pedido** é consultada **antes** de chamar o provedor: se já existe job com a mesma
+chave e resultado, reuse o artefato em vez de pagar de novo. É o que faz um retry — de fila, de
+worker reiniciado, de webhook duplicado — custar zero.
+
+A chave **de conteúdo** é o endereço do arquivo: `PutAsync` do mesmo conteúdo devolve o caminho já
+existente sem regravar. Dois pedidos diferentes podem produzir bytes idênticos; um pedido só sempre
+produz o mesmo pedido.
+
+Trocar a foto de referência muda a chave de pedido mesmo com prompt idêntico — por isso o sha256 de
+**cada** referência entra na fórmula, e não a contagem delas.
+
+---
+
+## Storage
+
+- **Bytes no blob próprio**, sempre. URL de provedor expira: o Veo apaga o arquivo em 2 dias, e todo
+  agregador devolve URL temporária.
+- O banco guarda **caminho relativo + sha256**, nunca URL absoluta de provedor e nunca o caminho
+  absoluto do disco de hoje.
+- O download acontece **no mesmo passo** que detectou a conclusão, antes de marcar `Generated`. Um
+  job em `Generated` sem bytes no seu storage está mentindo sobre o próprio estado.
+
+---
+
+## Proveniência persistida
+
+Um registro por job, gravado no momento da geração:
+
+| Campo | Por quê |
+|---|---|
+| `provider`, `modelId` | Sem eles, nenhuma auditoria de "que modelo gerou isto" é possível |
+| `promptFinal` | O texto que foi enviado, não o template |
+| `revisedPrompt` | O que o provedor reescreveu — frequentemente diferente do enviado |
+| `refsHash` | sha256 das referências, o mesmo que entra na chave de pedido |
+| `options` | Tamanho, qualidade, formato, background |
+| `responseId` | O id do lado do provedor, para abrir chamado |
+| `estimatedCostUsd` | Gravado **antes** da chamada — ver §Teto de custo |
+| `createdAt` | — |
+| `c2paPreserved` | Se os metadados sobreviveram ao seu pipeline |
+
+**Metadados C2PA são preservados: nada de re-encode destrutivo.** Um resize ou uma recompressão
+"para economizar CDN" apaga a credencial de conteúdo que o provedor embutiu, e você fica sem a única
+prova técnica de origem que tinha.
+
+---
+
+## Marcação, C2PA e SynthID
+
+As imagens das duas famílias já vêm com credencial embutida — **C2PA Content Credentials + SynthID**
+na OpenAI, **SynthID** em toda imagem Gemini — e a OpenAI expõe um endpoint
+`content_provenance_check` que verifica ambos.
+
+**E isso não basta**, por três razões escritas na própria documentação:
+
+1. **C2PA cai com screenshot e com re-encode.** Qualquer trânsito por uma ferramenta que reprocessa
+   o arquivo apaga a credencial. SynthID sobrevive melhor, mas não é infalível.
+2. **`not_detected` não significa "feito por humano".** A ausência de marca é ausência de
+   informação, nunca prova de origem.
+3. **A credencial é invisível para quem olha a imagem.** Um cliente no WhatsApp não roda verificador
+   de proveniência.
+
+Por isso **a marcação visível é obrigação separada**, aplicada no ponto de publicação e não no de
+geração.
+
+### Como esta obrigação é presa — e até onde ela chega
+
+Uma obrigação legal escrita só em prosa é a mesma coisa que nenhuma obrigação: alguém esquece, o
+teste fica verde, e o silêncio vira aprovação. No exemplar ela é **um parâmetro obrigatório da
+transição**, não um lembrete:
+
+```csharp
+public sealed record MediaDisclosure(string Text, string Surface, DateTimeOffset AppliedAt);
+
+// Texto E superfície são exigidos na construção: "marcado" sem dizer ONDE não responde
+// se alguém consegue ver, e texto em branco é o campo preenchido "para passar".
+public static bool RequiresDisclosure(this MediaPurpose purpose)
+    => purpose is MediaPurpose.CatalogPhoto or MediaPurpose.Marketing;
+```
+
+`MediaJob.Publish(null, at)` sobre um job de catálogo **aprovado** devolve falha nomeando a
+marcação. A mutação foi rodada: removida a terceira porta, os dois casos de
+`MediaDisclosureTests.PublishFailsWithoutADisclosureWhenThePurposeDemandsOne` morrem
+(`CatalogPhoto` e `Marketing`), a suíte cai de 220/0 para 220/2, e a mensagem de falha diz por quê.
+
+**O limite, dito em voz alta.** Isto prova que a **decisão foi tomada e gravada**, com texto e
+superfície nomeados — não que o rótulo chegou aos olhos de alguém. Nenhum tipo em C# alcança um
+pixel: a renderização é do aplicativo consumidor. O que o mecanismo elimina é o caminho silencioso
+"esquecemos de marcar", que passa a ser uma recusa na publicação.
+
+### EU AI Act art. 50
+
+O Regulamento (UE) 2024/1689 exige, no art. 50, transparência sobre conteúdo sintético: imagem
+gerada que **possa parecer autêntica** sobre produto, pessoa ou lugar exige aviso claro no primeiro
+contato.
+
+**Ressalva de fonte, declarada em vez de escondida.** O art. 113 do regulamento diz *"It shall apply
+from 2 August 2026"*, e o Capítulo IV — onde vive o art. 50 — **não tem data própria** naquele
+artigo; daí a leitura de que ele segue a data geral de **2026-08-02**. Essa derivação é **leitura do
+artigo, não citação de um considerando explícito**, e foi feita sobre
+`https://artificialintelligenceact.eu/article/113/`, uma fonte secundária que reproduz o texto.
+**Antes de o seu projeto assumir consequência jurídica** — prazo, multa, obrigação de rótulo —
+confira o mesmo artigo no EUR-Lex e registre a leitura com a data. Este standard afirma o
+mecanismo (marcar é obrigação de desenho); ele **não** é parecer jurídico, e escrever um número de
+multa aqui como se fosse fato verificado seria exatamente o defeito que ele combate.
+
+Regra de desenho, independente do prazo: **produto real sobre cena gerada é declarado como tal**, e
+nenhuma geração cria claim visual de material, medida ou cor que o produto não tem. Isso é
+codificado — uma lista de atributos bloqueados no validador do prompt — e não confiado ao texto do
+prompt.
+
+---
+
+## Revisão humana
+
+- `Approved` **exige humano** antes de `Published` para qualquer mídia de catálogo ou peça pública.
+- O revisor é identificado e carimbado com data no `MediaReview` — "aprovado" sem quem e sem quando
+  não é revisão, é campo booleano.
+- **Juiz LLM é pré-filtro, nunca substituto.** Ele derruba as candidatas obviamente ruins e economiza
+  o tempo do humano; ele não assume a responsabilidade de um claim visual.
+- O gate humano natural é a **escolha entre N candidatas** geradas em qualidade baixa. A escada de
+  custo e a revisão são o mesmo passo, não dois.
+
+---
+
+## Teto de custo
+
+- **Orçamento por tenant/dia em unidades**, não em reais: imagens × qualidade para imagem, segundos
+  de saída para vídeo. Unidade é o que o provedor cobra; moeda é derivada.
+- **`estimatedCostUsd` é gravado antes da chamada**, com a tarifa da tabela de preço do standard da
+  modalidade (`modalities-image-gen.md` §Custo por chamada, `media-video.md` §Custo por segundo).
+  Estimar depois é contabilidade; estimar antes é controle.
+- Estouro de teto é recusa **no enqueue**, com erro nomeado — nunca uma chamada que já saiu e um
+  alerta que chega depois.
+
+---
+
+## Telemetria
+
+Quatro séries, por modelo, e cada uma responde a uma pergunta que alguém vai fazer:
+
+| Série | Pergunta |
+|---|---|
+| Latência | "Por que o cliente ainda não recebeu?" |
+| Custo | "Quanto gastamos com isto no mês?" |
+| Taxa de rejeição por política | "Nosso prompt está pedindo o que o provedor não faz?" |
+| Taxa de aprovação humana | "O modelo que escolhemos serve para este trabalho?" |
+
+A última é a que ninguém instrumenta e a que mais decide: um modelo com 30 % de aprovação humana é
+mais caro que um modelo com o dobro da tarifa e 90 %.
+
+---
+
+## Testes
+
+- **Nenhum teste chama API paga.** Provider fake implementando a mesma abstração interna, store em
+  memória. Isso não é preferência: é a única forma de a suíte rodar em CI sem chave e sem fatura.
+- O que se testa é o **mecanismo**: que `Publish` falha fora de `Approved`; que `RejectedByPolicy`
+  não oferece retry; que a chave de pedido é estável para o mesmo pedido e muda quando qualquer campo
+  participante muda; que gravar o mesmo conteúdo duas vezes grava uma.
+- **Teste de acessibilidade por reflexão** para a regra dura: o tipo que produz bytes não é público.
+  Torná-lo público tem de derrubar esse teste — e vale rodar a mutação uma vez para ver.
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Nenhum handler síncrono consegue nomear o tipo que produz bytes
+- [ ] Nenhum `await runner.RunAsync(...)` dentro de handler de turno — **o tipo não fecha esta
+      porta** (o runner é público de propósito); quem a fecha é a revisão de código
+- [ ] A superfície pública devolve id de job, nunca bytes
+- [ ] Os oito estados existem, e `Publish` falha fora de `Approved`
+- [ ] `Publish` recusa sem marcação quando a finalidade a exige — e o teste dessa recusa existe
+- [ ] Bloqueio de moderação é `rejected_by_policy`, sem retry
+- [ ] Chave de **pedido** consultada antes da chamada paga; chave de **conteúdo** endereça o storage
+- [ ] Bytes no blob próprio; banco com caminho relativo + sha256
+- [ ] Proveniência com os nove campos, C2PA preservado sem re-encode
+- [ ] Marcação visível aplicada no ponto de publicação, com texto **e** superfície nomeados
+- [ ] `Approve` carimba revisor e data
+- [ ] `estimatedCostUsd` gravado antes da chamada; teto por tenant/dia recusa no enqueue
+- [ ] Telemetria com as quatro séries, incluindo taxa de aprovação humana
+- [ ] Nenhum teste toca API paga
+
+---
+
+## Como re-verificar este standard
+
+| Página | O que conferir |
+|---|---|
+| `https://developers.openai.com/api/docs/guides/content-provenance` | Se `content_provenance_check` mudou, e a afirmação de que C2PA cai com re-encode |
+| `https://ai.google.dev/gemini-api/docs/image-generation` | Se SynthID continua em toda imagem Gemini |
+| `https://eur-lex.europa.eu/eli/reg/2024/1689/oj` | O art. 50 e o art. 113 no texto oficial — é a fonte primária que a §EU AI Act ainda não tem |
+| `https://ai.google.dev/gemini-api/docs/veo` | A retenção de 2 dias citada em §Storage |
+| `modalities-image-gen.md` e `media-video.md` | As tabelas de preço que este standard referencia sem copiar |
+
+Ao terminar, atualize `Last-verified` **e** o `ai-pin` citado no header.
+
+---
+
+## References
+
+- `ai-agents/modalities-image-gen.md` — a chamada de imagem, os aliases e o custo
+- `ai-agents/media-video.md` — a chamada de vídeo, o polling e o custo por segundo
+- `backend/integrations/hangfire/hangfire-jobs.md` — o mecanismo de job: enqueue, retry,
+  `IDbContextFactory`, dashboard. Este standard **cita** e não reescreve
+- `ai-agents/durable-workflows-hitl.md` — HITL dentro de um Workflow MAF; a outra coisa
+- `ai-agents/production.md` — custo por chamada, teste sem rede, observabilidade
+- `ai-agents/batching.md` — o desconto de lote que o catálogo usa
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/media-pipeline.md v1.0*

package/framework/standards/ai-agents/media-video.md

@@ -0,0 +1,267 @@
+# Media — Video Generation (runtime, a partir de .NET)
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** video generation, veo, seedance, kling, runway, image to video, text to video, media video
+> **Read by Claude in:** implement (quando o projeto precisa gerar vídeo em runtime)
+
+**Verified against:** Google.GenAI 1.21.0 + OpenAI 2.13.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/VeoVideoProvider.cs` — `Models.GenerateVideosAsync(model, GenerateVideosSource, GenerateVideosConfig, ct)`, o polling por `Operations.GetAsync` + `operation.Done` e o sinal de bloqueio `RaiMediaFilteredCount` COMPILAM ali. Preço, duração, retenção e data de desligamento são **verificação documental** contra as páginas listadas em §Como re-verificar este standard. Last-verified: 2026-09-08.
+
+---
+
+**A fronteira, primeiro.** Este standard é sobre **gerar vídeo em runtime a partir de .NET**: o
+backend cria uma tarefa paga, faz polling, baixa bytes e guarda. Footage de landing page
+scroll-driven, produzido por MCP em **tempo de autoria**, é
+`frontend/design-system/ai-video-generation.md` — loop × direcional, `endImage`, o contorno de
+moderação E005 e a escada de custo daquele fluxo. Os dois se citam e não se sobrepõem: lá o
+operador é um designer numa sessão; aqui é um worker no seu servidor.
+
+O pipeline (job, revisão, publicação, marcação) é `ai-agents/media-pipeline.md`. Imagem é
+`ai-agents/modalities-image-gen.md`.
+
+---
+
+## Quando usar
+
+| Caso | Nota |
+|---|---|
+| **Vídeo curto de produto** (reels, stories, até 8 s com áudio) | O caso que paga a conta |
+| **Animar render de cliente** | `img2vid` sobre a arte real, nunca recriação por IA |
+| **Variação de cena** sobre um herói aprovado | Depois da aprovação da imagem, nunca antes |
+
+**Nunca dentro de um turno de conversa.** A geração de vídeo leva de **11 s a 6 min** medidos na
+documentação do Veo, é assíncrona **por desenho em todos os provedores** — nenhum deles devolve o
+arquivo na resposta do POST — e custa por segundo de saída. Não existe forma de fazer isso caber num
+turno de WhatsApp; a tentativa é `ai-agents/media-pipeline.md` §A regra dura.
+
+---
+
+## O caminho com SDK
+
+`Google.GenAI` 1.21.0, `net8.0` + `netstandard2.0`. É o **único** caminho com SDK .NET oficial
+depois do desligamento listado em §Deprecações.
+
+```csharp
+using Google.GenAI.Types;
+
+// 1. Cria a operacao. Ela volta NAO-concluida: o video ainda nao existe.
+//    O prompt vai DENTRO de GenerateVideosSource — nao e um parametro solto.
+var operation = await client.Models.GenerateVideosAsync(
+    "veo-3.1-fast-generate-preview",
+    new GenerateVideosSource { Prompt = prompt },
+    new GenerateVideosConfig { DurationSeconds = 8, AspectRatio = "16:9" },
+    ct);
+
+// 2. Polling. ~10 s entre voltas e o intervalo que a doc do Veo usa; back-off e
+//    TETO DE TENTATIVAS — um laco sem saida e indistinguivel de um worker travado.
+//    `Done` e bool? : `!operation.Done` NAO compila; compare com true.
+for (var poll = 0; operation.Done != true && poll < 60; poll++)
+{
+    await Task.Delay(TimeSpan.FromSeconds(10), ct);
+    operation = await client.Operations.GetAsync(operation, new GetOperationConfig(), ct);
+}
+
+// 3. Bloqueio de moderacao NAO e erro tecnico, e o sinal e este:
+if (operation.Response?.RaiMediaFilteredCount is > 0) { /* rejected_by_policy, sem retry */ }
+
+// 4. BAIXE OS BYTES AGORA (operation.Response.GeneratedVideos[..].Video.VideoBytes).
+//    Ver a secao "O arquivo expira".
+```
+
+> **Assinaturas medidas contra `Google.GenAI` 1.21.0 por reflexão, não lidas em blog.** Três
+> detalhes derrubam o build de quem copia de uma página de terceiro: o prompt viaja em
+> `GenerateVideosSource`, `Operations.GetAsync` pede um `GetOperationConfig` (não só o token), e
+> `operation.Done` é `bool?` — `while (!operation.Done)` não compila. O exemplar que compila está
+> em `templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/VeoVideoProvider.cs`.
+
+Três exigências de desenho que caem deste formato, e não são opcionais:
+
+1. **O `operation` é estado persistido**, não variável local. Se o worker reiniciar no meio, o id da
+   operação tem de estar no banco — senão você paga de novo por um vídeo que já está pronto.
+2. **O polling mora num job**, nunca numa request HTTP. Um `while` de 6 minutos dentro de um
+   controller é um thread pool derretido.
+3. **Timeout e teto de tentativas explícitos.** `Done` que nunca vira `true` é um caso real, e um
+   loop sem saída é indistinguível de um worker travado.
+
+---
+
+## O caminho sem SDK
+
+Seedance 2.0 (BytePlus ModelArk ou fal.ai), Kling 3.0 e Runway **não têm SDK .NET**. Sem exceção,
+sem "biblioteca da comunidade": `HttpClient` **tipado** via `IHttpClientFactory`, DTOs próprios,
+`System.Text.Json` com source generation, e Polly para 429/5xx/timeout.
+
+O contrato é o mesmo nos três, e é o que torna o adaptador escrevível:
+
+```
+POST criar tarefa  →  { id }        (202 / 200, NUNCA o arquivo)
+        ↓  persistir o id ANTES de qualquer outra coisa
+GET status(id)     →  queued | running | succeeded | failed
+        ↓  polling com back-off, OU webhook (fal.ai, Runway)
+GET resultado      →  URL temporaria  →  baixar  →  blob proprio
+```
+
+**Persistir o id antes de qualquer outra coisa** é a linha que separa "retry custa zero" de "retry
+custa outra geração". O resto do desenho — chave de idempotência, estados, storage — está em
+`ai-agents/media-pipeline.md`.
+
+Webhook, onde existe, é preferível a polling: menos chamada, menos latência de detecção. Mas o
+polling continua sendo o caminho de recuperação quando o webhook se perde — implemente os dois, e
+faça o handler de webhook idempotente.
+
+---
+
+## Sora: não planejar
+
+`sora-2`, `sora-2-pro` e o `VideoClient` do `openai-dotnet` (`CreateVideo`, `GetVideo`,
+`DownloadVideo`, `CreateVideoRemix`) **saem de circulação sem substituto** — a data está em
+§Deprecações. "Sem substituto" é literal: a OpenAI não anunciou modelo de vídeo sucessor.
+
+Consequência prática: **não escreva adaptador para Sora**, não pine alias de Sora, e se encontrar um
+num projeto existente, a migração é para o caminho com SDK do Google ou para um dos HTTP crus. Um
+adaptador escrito hoje para Sora nasce morto.
+
+---
+
+## Custo por segundo
+
+> **Toda a aritmética de dinheiro deste standard mora nesta seção, e em lugar nenhum mais.**
+
+Preço de **lista pública**, em USD por segundo de saída, sem desconto de contrato. Consultadas em
+**2026-09-07**: `https://ai.google.dev/gemini-api/docs/veo` com
+`https://ai.google.dev/gemini-api/docs/pricing`, `https://docs.byteplus.com/en/docs/ModelArk/1520757`,
+`https://fal.ai/models/bytedance/seedance-2.0/image-to-video`, `https://kling.ai/dev/pricing` e
+`https://docs.dev.runwayml.com/guides/pricing/`.
+
+| Modelo | Preço | Nota |
+|---|---|---|
+| Veo 3.1 **Lite** | $0,05 / s | Sem 4K |
+| Veo 3.1 **Fast** — 720p | $0,10 / s | O default recomendado; áudio incluso |
+| Veo 3.1 Standard — 720p/1080p | $0,40 / s | 4K: $0,60 / s |
+| Seedance 2.0 (BytePlus oficial) | $0,04 – $0,78 / s | Varia por modelo e resolução; pacote pré-pago mínimo de $30,10 |
+| Seedance 2.0 (fal.ai) | $0,3024 / s std 720p; $0,2419 / s fast | Mesmo modelo, agregador diferente, preço diferente |
+| Kling 3.0 std | ≈ $0,42 por 5 s | Sem SDK |
+| Runway gen4.5 | $0,12 / s | Créditos a $0,01; 12 cr/s |
+
+Três leituras que decidem projeto:
+
+1. **A faixa do Seedance é de 20× entre o piso oficial e o teto**, e o mesmo modelo custa preços
+   diferentes conforme o agregador. Por isso **nenhum alias default é pinado** para Seedance, Kling
+   ou Runway neste standard: escolher um seria escolher fornecedor por conveniência de escrita, e não
+   por evidência. Meça o seu caso antes de pinar.
+2. **Vídeo é caro por segundo e mínimo de 4 s.** Um rascunho de 4 s em Lite custa uma fração de um
+   final de 8 s em Standard — a escada de custo é a mesma disciplina de imagem, com números maiores.
+3. **Bloqueio de moderação no Veo não cobra.** Isso muda o desenho de retry: um bloqueio é
+   `rejected_by_policy` e não deve ser retentado; um erro técnico é `failed` e deve.
+
+---
+
+## Duração, resolução e referências
+
+Medido contra `https://ai.google.dev/gemini-api/docs/veo` (Veo 3.1) e a doc do BytePlus ModelArk
+(Seedance 2.0), ambas consultadas na data declarada em §Custo por segundo.
+
+| Parâmetro | Veo 3.1 | Seedance 2.0 |
+|---|---|---|
+| Duração | 4, 6 ou 8 s | 4 a 15 s |
+| **8 s é obrigatório** para | 1080p, 4K e uso de imagens de referência | — |
+| Aspect ratio | 16:9 ou 9:16 | 480p / 720p / 1080p |
+| Frame rate | 24 fps | — |
+| Áudio | nativo, incluso no preço | nativo |
+| Imagem inicial | sim (primeiro frame) | JPEG/PNG/WebP até 30 MB |
+| Interpolação | primeiro + último frame | imagem final opcional |
+| Referências | **até 3 imagens** (exige 8 s) | referências de vídeo e áudio |
+| Extensão | +7 s, até 20 vezes (720p) | — |
+
+"8 s obrigatório para referências" é a pegadinha cara: pedir 4 s **com** imagem de referência é uma
+requisição inválida, e descobrir isso em produção custa uma rodada de suporte.
+
+---
+
+## O arquivo expira
+
+O Veo retém o arquivo gerado por **2 dias**. Depois disso a URL devolve 404 e o vídeo pelo qual você
+pagou não existe mais em lugar nenhum.
+
+**Baixar e gravar no blob próprio é obrigação, não otimização.** O download entra no mesmo passo do
+worker que detectou `Done`, antes de qualquer outra coisa; o banco guarda caminho relativo + sha256,
+nunca a URL do provedor. O mesmo vale para todo agregador: URL de resultado é sempre temporária.
+
+Um job que marcou `generated` sem ter baixado os bytes está mentindo sobre o próprio estado. Ver
+`ai-agents/media-pipeline.md` §Storage.
+
+---
+
+## Moderação e pessoas
+
+- **Bloqueio não cobra** (Veo). Trate-o como `rejected_by_policy`: estado terminal, **sem retry**.
+  Retentar um bloqueio é gastar dinheiro para receber o mesmo "não" — e nos provedores que cobram o
+  bloqueio, é gastar duas vezes.
+- **`personGeneration` é restrito por região.** O mesmo prompt aprovado num mercado é recusado em
+  outro; a política tem de ser por tenant, não global.
+- **Rostos disparam moderação com frequência.** O motivo e o contorno operacional (enquadrar do
+  pescoço para baixo, mãos, produto; reservar rosto para imagem estática) estão escritos em
+  `frontend/design-system/ai-video-generation.md` §Section 3 — este standard cita e não repete.
+- **Nunca gere rosto de cliente real.** Além do risco jurídico, é o caso que a marcação obrigatória
+  do `media-pipeline.md` foi feita para cobrir.
+
+---
+
+## Deprecações
+
+> **Toda data de desligamento deste standard mora nesta seção, e em lugar nenhum mais.**
+
+Fonte, consultada em **2026-09-07**: `https://developers.openai.com/api/docs/deprecations`.
+
+| Alias / superfície | Situação | Data |
+|---|---|---|
+| `sora-2`, `sora-2-pro` e a Videos API | **desligam, sem substituto** (anunciado 2026-03-24) | 2026-09-24 |
+| `VideoClient` do `openai-dotnet` | morre junto com a API acima | 2026-09-24 |
+
+**Próximo desligamento conhecido: 2026-09-24.** Se esta data já passou quando você está lendo, este
+standard não está apenas velho — ele está **errado** em pelo menos uma afirmação, e a §Como
+re-verificar diz qual página conferir. É falsificável em segundos, sem pesquisa.
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Nenhum código novo aponta para um alias de §Deprecações
+- [ ] O id da operação/tarefa é **persistido antes** do primeiro polling
+- [ ] O polling roda num job, com back-off e teto de tentativas — nunca numa request HTTP
+- [ ] Os bytes são baixados assim que a tarefa conclui, e gravados em blob próprio
+- [ ] O banco guarda caminho relativo + sha256, nunca a URL do provedor
+- [ ] Bloqueio de moderação é estado terminal `rejected_by_policy`, sem retry
+- [ ] Duração pedida respeita o mínimo do provedor (8 s no Veo quando há referência)
+- [ ] Custo estimado gravado antes da chamada, com a tarifa de §Custo por segundo
+- [ ] Nenhuma geração dentro de um turno de conversa
+- [ ] Nenhum teste toca API paga — provider fake, sempre
+
+---
+
+## Como re-verificar este standard
+
+| Página | O que conferir |
+|---|---|
+| `https://developers.openai.com/api/docs/deprecations` | A tabela de §Deprecações e a linha "próximo desligamento conhecido" |
+| `https://ai.google.dev/gemini-api/docs/veo` | Duração, resolução, limite de referências, retenção de 2 dias, `personGeneration` |
+| `https://ai.google.dev/gemini-api/docs/pricing` | As três linhas Veo de §Custo por segundo |
+| `https://docs.byteplus.com/en/docs/ModelArk/1520757` e `https://fal.ai/models/bytedance/seedance-2.0/image-to-video` | A faixa de preço do Seedance nos dois canais |
+| `https://www.nuget.org/packages/Google.GenAI` | Se `GenerateVideosAsync`/`Operations.GetAsync` mudaram de forma |
+
+Ao terminar, atualize `Last-verified` **e** o `ai-pin` citado no header.
+
+---
+
+## References
+
+- `ai-agents/media-pipeline.md` — o job, os estados, a idempotência, a marcação
+- `ai-agents/modalities-image-gen.md` — imagem em runtime, e a escada de custo irmã desta
+- `frontend/design-system/ai-video-generation.md` — footage direcional para scroll scrub via MCP:
+  loop × direcional, `endImage`, moderação E005. Consumidor diferente, tempo diferente
+- `ai-agents/providers/model-registry.md` — o alias por provedor, com `api: videos`
+- `backend/integrations/hangfire/hangfire-jobs.md` — o mecanismo de job que o polling usa
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/media-video.md v1.0*