@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/framework/standards/ai-agents/mcp-tools.md

@@ -2,10 +2,10 @@
 
 > **Scope:** stacks=["dotnet"]
 > **Layer:** 2 (on-keyword)
-> **Keywords:** mcp, model context protocol, mcp client, consume mcp server, mcp tools, external tools
+> **Keywords:** mcp, model context protocol, mcp client, consume mcp server, mcp tools, external tools, McpClient, HttpClientTransport, MRTR
 > **Read by Claude in:** implement (quando um agente usa tools de um MCP server externo)
 
-**Verified against:** MAF 1.0 GA + ModelContextProtocol C# SDK. Last-verified: 2026-05-19.
+**Verified against:** ModelContextProtocol 2.2.0 + Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08) + revisão de spec MCP **2026-07-28**. **Verificação documental — o ai-kit não exercita MCP**, e por isso este standard NÃO carimba `provado por`. Todos os nomes de tipo abaixo foram **medidos por reflexão sobre `ModelContextProtocol.Core` 2.2.0** em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
@@ -27,27 +27,71 @@ Casos de uso típicos:
 **Package:**
 
 ```xml
-<PackageReference Include="ModelContextProtocol" Version="0.1.*" />
+<!-- no ai-pin.json -->
+<PackageReference Include="ModelContextProtocol" Version="2.2.0" />
+
+<!-- SÓ se o servidor expuser tools long-running. Fora do pin; apurado no nuget.org em 2026-09-08. -->
+<PackageReference Include="ModelContextProtocol.Extensions.Tasks" Version="2.2.0" />
 ```
 
-> O pacote `ModelContextProtocol` é o SDK C# oficial do protocolo. Versão 0.1.* (preview) — GA previsto; verifique no NuGet antes de travar versão.
+> O SDK C# saiu do preview: **2.2.0**, publicado em 2026-08-13. A faixa `0.1.*` que este standard trazia é de duas majors atrás.
+
+### Renomes da 2.x — o que não compila mais
+
+| Nome antigo (0.1.x / 1.x) | Nome atual, **medido em 2.2.0** |
+|---|---|
+| `McpClientFactory.CreateAsync(transport)` | **`McpClient.CreateAsync(transport)`** — estático em `McpClient` |
+| `SseClientTransport` | **`HttpClientTransport`** com `HttpClientTransportOptions.TransportMode = HttpTransportMode.Sse` |
+
+`McpClientFactory` e `SseClientTransport` **não existem** em `ModelContextProtocol.Core` 2.2.0 — verificado por varredura dos tipos exportados. Não são alternativas; são nomes mortos.
 
 **Fluxo de consumo:**
 
-1. `McpClientFactory.CreateAsync(transport)` — conecta ao MCP server e retorna um client `IDisposable`
+1. `McpClient.CreateAsync(transport)` — conecta ao MCP server e devolve um client descartável
 2. `mcpClient.ListToolsAsync()` — descobre as tools disponíveis no servidor
-3. `mcpTools.Cast<AITool>()` — converte para `AITool` (interface do MAF / `Microsoft.Extensions.AI`)
-4. Passa as tools ao agente via `AsAIAgent(..., tools: [.. mcpTools.Cast<AITool>()])`
+3. Passa as tools ao agente via `AsAIAgent(..., tools: [.. mcpTools])`
+
+**`McpClientTool` herda de `AIFunction`.** Medido: `ModelContextProtocol.Client.McpClientTool : Microsoft.Extensions.AI.AIFunction`, e `AIFunction` é um `AITool`. Ou seja, **o `.Cast<AITool>()` é desnecessário** em qualquer ponto que aceite `IEnumerable<AITool>` — a conversão é implícita por herança. Mantenha o cast apenas quando precisar de um `AITool[]` a partir de um `Concat` de coleções de tipos diferentes.
 
-**Transports suportados:**
+**Transports suportados (medidos):**
 
-| Transport | Classe | Quando usar |
-|-----------|--------|------------|
-| stdio | `StdioClientTransport` | MCP server local (processo filho — `npx`, executável) |
-| HTTP (SSE) | `SseClientTransport` | MCP server remoto via HTTP/SSE |
+| Transport | Classe | Opções | Quando usar |
+|-----------|--------|--------|------------|
+| stdio | `StdioClientTransport` | `StdioClientTransportOptions`: `Name`, `Command`, `Arguments`, `WorkingDirectory`, `EnvironmentVariables`, `ShutdownTimeout` | MCP server local (processo filho — `npx`, executável) |
+| Streamable HTTP | `HttpClientTransport` | `HttpClientTransportOptions`: `Endpoint`, `TransportMode` (`AutoDetect` \| `StreamableHttp` \| `Sse`), `AdditionalHeaders`, `OAuth`, `ConnectionTimeout` | MCP server remoto |
+
+`HttpTransportMode.Sse` existe para falar com servidores da era HTTP+SSE, que a revisão `2026-07-28` marcou como **Deprecated**. Para servidor novo, `StreamableHttp` (ou `AutoDetect`).
 
 **Regra importante:** use `await using` no `mcpClient` — o dispose fecha o transporte corretamente.
 
+### Modo stateless quebra três métodos
+
+A revisão `2026-07-28` removeu as sessões, e o servidor C# 2.2.0 nasce **stateless por default**. Consequência para quem escreve **cliente**: `ElicitAsync`, `SampleAsync` e `RequestRootsAsync` dependem de uma sessão persistente e de requests server→client, e **falham** contra um servidor stateless. Sampling e Roots estão, além disso, **deprecados** pela SEP-2577 — o próprio `McpServerOptions.MaxSamplingOutputTokens` carrega essa frase no `[Obsolete]`.
+
+A via que funciona nas duas configurações é o **MRTR** (*More-Round-Trip Response*), medido em `ModelContextProtocol.Protocol`:
+
+```csharp
+// No SERVIDOR: em vez de chamar de volta o cliente, devolva o pedido de input.
+throw new InputRequiredException(new InputRequiredResult
+{
+    RequestState = state,
+    InputRequests = { ["confirm"] = InputRequest.ForElicitation(elicitParams) },
+});
+
+// No CLIENTE: responda os pedidos e siga.
+await mcpClient.ResolveInputRequestsAsync(answers, ct);
+```
+
+`InputRequest` tem as três fábricas `ForElicitation`, `ForSampling` e `ForRootsList`.
+
+### Tasks (long-running) mudaram de pacote E de wire
+
+Long-running saiu do core para **`ModelContextProtocol.Extensions.Tasks`** (2.2.0, apurado em 2026-09-08). **Não há compatibilidade de wire** com a implementação experimental das 1.3/1.4: quem usava aquilo **migra**, não apenas sobe a versão. Sinal de que é preciso migrar: código que fala tasks e continua compilando depois do upgrade — o formato mudou no fio, não na API.
+
+### Custo de definição de tool por turno
+
+Toda tool descoberta entra na **definição** enviada ao modelo a cada turno — nome, descrição e JSON Schema dos parâmetros. Um servidor MCP com 60 tools cobra isso em todo request, mesmo nos turnos em que nenhuma é chamada. Pode-se podar com `mcpClient.RemoveKnownTools([...])` / `AddKnownTools([...])`, ou registrando só o recorte relevante no agente. O critério de quantas tools cabem num agente é de `ai-agents-sweet-spot` — não é duplicado aqui.
+
 ---
 
 ## Exemplo C#
@@ -61,7 +105,7 @@ using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
 // 1. Conectar ao MCP server (GitHub via npx)
-await using var mcpClient = await McpClientFactory.CreateAsync(
+await using var mcpClient = await McpClient.CreateAsync(
     new StdioClientTransport(new()
     {
         Name = "GitHubServer",
@@ -70,14 +114,15 @@ await using var mcpClient = await McpClientFactory.CreateAsync(
     }));
 
 // 2. Descobrir as tools do servidor
-var mcpTools = await mcpClient.ListToolsAsync();
+IList<McpClientTool> mcpTools = await mcpClient.ListToolsAsync();
 
 // 3. Criar o agente MAF com as MCP tools registradas
-// _modelRegistry vem de IModelRegistry (ai-agents-providers-model-registry)
+// McpClientTool herda de AIFunction (que é AITool) — sem cast.
+// _modelRegistry vem de ModelRegistry (ai-agents-providers-model-registry)
 AIAgent agent = _modelRegistry.GetChatClient("text-default")
     .AsAIAgent(
         instructions: "You answer questions about GitHub repositories.",
-        tools: [.. mcpTools.Cast<AITool>()]);
+        tools: [.. mcpTools]);
 
 // 4. Usar o agente normalmente
 var response = await agent.RunAsync(
@@ -85,16 +130,17 @@ var response = await agent.RunAsync(
 Console.WriteLine(response.Text);
 ```
 
-**Variante com MCP server remoto (HTTP/SSE):**
+**Variante com MCP server remoto (Streamable HTTP):**
 
 ```csharp
 using ModelContextProtocol.Client;
 
-await using var mcpClient = await McpClientFactory.CreateAsync(
-    new SseClientTransport(new()
+await using var mcpClient = await McpClient.CreateAsync(
+    new HttpClientTransport(new HttpClientTransportOptions
     {
         Name = "RemoteToolsServer",
-        Uri = new Uri("https://tools.example.com/mcp"),
+        Endpoint = new Uri("https://tools.example.com/mcp"),
+        TransportMode = HttpTransportMode.StreamableHttp,   // .Sse só para servidor legado
     }));
 
 var mcpTools = await mcpClient.ListToolsAsync();
@@ -105,7 +151,7 @@ var mcpTools = await mcpClient.ListToolsAsync();
 
 ```csharp
 // Conectar a dois servidores e combinar as tools
-await using var githubClient = await McpClientFactory.CreateAsync(
+await using var githubClient = await McpClient.CreateAsync(
     new StdioClientTransport(new()
     {
         Name = "GitHub",
@@ -113,7 +159,7 @@ await using var githubClient = await McpClientFactory.CreateAsync(
         Arguments = ["-y", "@modelcontextprotocol/server-github"],
     }));
 
-await using var fsClient = await McpClientFactory.CreateAsync(
+await using var fsClient = await McpClient.CreateAsync(
     new StdioClientTransport(new()
     {
         Name = "Filesystem",
@@ -121,10 +167,10 @@ await using var fsClient = await McpClientFactory.CreateAsync(
         Arguments = ["-y", "@modelcontextprotocol/server-filesystem", "/repo"],
     }));
 
-var allTools = (await githubClient.ListToolsAsync())
-    .Concat(await fsClient.ListToolsAsync())
-    .Cast<AITool>()
-    .ToArray();
+AITool[] allTools = [
+    .. await githubClient.ListToolsAsync(),
+    .. await fsClient.ListToolsAsync(),
+];   // McpClientTool : AIFunction : AITool — a conversão é por herança
 
 AIAgent agent = _modelRegistry.GetChatClient("text-default")
     .AsAIAgent(
@@ -164,7 +210,11 @@ AIAgent agent = _modelRegistry.GetChatClient("text-default")
 |-------------|---------|---------|
 | Criar um MCP server próprio só para o agente do mesmo projeto chamar | Overhead desnecessário de protocolo e deploy | Escrever tool nativa com `[Description]` + `AIFunctionFactory.Create()` |
 | Não tratar indisponibilidade do MCP server | O MCP server pode estar offline ou lento; o agente quebra | Usar `ResilientToolMiddleware` para capturar `HttpRequestException` e `TimeoutException` (ver `ai-agents-production`) |
-| Não usar `await using` no `mcpClient` | Processo filho (npx) fica zumbi; leak de recursos | Sempre `await using var mcpClient = await McpClientFactory.CreateAsync(...)` |
+| Não usar `await using` no `mcpClient` | Processo filho (npx) fica zumbi; leak de recursos | Sempre `await using var mcpClient = await McpClient.CreateAsync(...)` |
+| Usar `McpClientFactory` ou `SseClientTransport` | Não existem na 2.x — o código não compila | `McpClient.CreateAsync` e `HttpClientTransport` |
+| Contar com `ElicitAsync` / `SampleAsync` / `RequestRootsAsync` | Exigem sessão persistente; o servidor 2.2.0 é stateless por default, e Sampling/Roots estão deprecados (SEP-2577) | MRTR: `InputRequiredException` + `InputRequest.ForElicitation(...)` |
+| Só subir a versão do pacote de Tasks vindo das 1.3/1.4 | Não há compatibilidade de **wire**; compila e falha no fio | Migrar para `ModelContextProtocol.Extensions.Tasks` conscientemente |
+| Registrar as 60 tools de um servidor "porque estavam lá" | A definição de toda tool é reenviada a cada turno | Podar (`RemoveKnownTools`) ou registrar só o recorte; critério em `ai-agents-sweet-spot` |
 | Hardcodar o model diretamente (`new ChatClient("gpt-4o", key)`) | Viola provider-agnostic; difícil de trocar | Sempre `_modelRegistry.GetChatClient("alias")` (ver `ai-agents-providers-model-registry`) |
 
 
@@ -172,11 +222,12 @@ AIAgent agent = _modelRegistry.GetChatClient("text-default")
 
 ## Checklist (verifiable by morph-eval)
 
-- [ ] `ModelContextProtocol` presente no `.csproj`
+- [ ] `ModelContextProtocol` presente no `.csproj` com versão exata (2.2.0 no pin) — sem faixa flutuante
 - [ ] `await using var mcpClient` — dispose correto do transporte
-- [ ] `McpClientFactory.CreateAsync(new StdioClientTransport(...))` com `Name`, `Command`, `Arguments`
+- [ ] `McpClient.CreateAsync(...)` — nenhuma ocorrência de `McpClientFactory` ou `SseClientTransport`
 - [ ] `ListToolsAsync()` chamado antes de criar o agente
-- [ ] `mcpTools.Cast<AITool>()` para registrar no agente
+- [ ] Nenhum `.Cast<AITool>()` supérfluo (`McpClientTool` já é `AIFunction`)
+- [ ] Nenhum `ElicitAsync`/`SampleAsync`/`RequestRootsAsync` contra servidor stateless
 - [ ] Agente criado via `_modelRegistry.GetChatClient("alias").AsAIAgent(...)` — provider-agnostic
 - [ ] `ResilientToolMiddleware` ou equivalente registrado (o MCP server pode ficar indisponível)
 - [ ] Nenhum `Guid.NewGuid()` — usar `Guid.CreateVersion7()` se IDs são necessários
@@ -189,9 +240,11 @@ AIAgent agent = _modelRegistry.GetChatClient("text-default")
 - `ai-agents-production` — panorama de MCP Integration, `ResilientToolMiddleware`, middleware pipeline
 - `ai-agents-mcp-server` — expor capacidades do próprio projeto como MCP server
 - `integration/mcp/mcp-tools.md` — MCPs no workflow do morph-spec (Playwright, Context7, Neon) — contexto complementar, escopo diferente
-- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
+- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) — `docs/concepts/**` (lido 2026-09-08)
+- [MCP — versionamento da especificação](https://modelcontextprotocol.io/specification/versioning) — revisão corrente `2026-07-28` (lido 2026-09-08)
+- [NuGet — ModelContextProtocol 2.2.0](https://www.nuget.org/packages/ModelContextProtocol/2.2.0) (publicado 2026-08-13)
 - [Using MCP Tools — MAF docs](https://learn.microsoft.com/agent-framework/user-guide/model-context-protocol/using-mcp-tools)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/mcp-tools.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/mcp-tools.md v2.0 (2026-09-08)*

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*