@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Evals/ShortPathResponseCache.cs

@@ -0,0 +1,349 @@
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI.Evaluation.Reporting;
+using Microsoft.Extensions.Caching.Distributed;
+
+namespace Morph.AiKit.Evals;
+
+/// <summary>
+/// A cache de respostas em disco do kit, com caminhos CURTOS o bastante para serem
+/// commitados e instalados no Windows.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que não usamos o <c>DiskBasedResponseCacheProvider</c> da biblioteca.</b> Ele nomeia
+/// o diretório de cada entrada com o hash inteiro em hexadecimal — <b>96 caracteres</b>. Somado
+/// ao resto (<c>cache/{cenário}/{iteração}/</c>, mais o nome do arquivo), o caminho relativo
+/// chega a <b>225</b> caracteres; com a raiz deste repositório (73) o absoluto dá <b>298</b>,
+/// contra o teto de <b>260</b> do <c>MAX_PATH</c> do Windows.
+/// </para>
+/// <para>
+/// <b>O sintoma foi pior que o erro.</b> O git não recusou barulhento: ele avisou
+/// <c>could not open directory ... Filename too long</c> e commitou <b>1 de 9</b> arquivos — só
+/// o carimbo. A árvore de cache "commitada" não existia no commit, e o canário de CI
+/// (<c>git diff --exit-code</c>) reportava LIMPO porque o git nunca enxergou os arquivos.
+/// Um guarda que não consegue observar o objeto reporta verde por construção.
+/// </para>
+/// <para>
+/// <b>O que muda, e só isso:</b> o segmento de hash passa a ser um PREFIXO de
+/// <see cref="KeyLength"/> caracteres do mesmo hash. O resto do layout é o da biblioteca —
+/// <c>cache/{cenário}/{iteração}/{chave}/{entry.json,contents.data}</c>.
+/// </para>
+/// <para>
+/// <b>Truncar é seguro AQUI por construção, e não por contagem de bits.</b> O
+/// <c>entry.json</c> guarda a chave INTEIRA, e a leitura compara: prefixo que colide com outra
+/// chave devolve <b>miss</b>, nunca a resposta errada. Um miss é caro (regravar) e visível
+/// (o modo offline reprova nomeando o cenário); uma resposta trocada seria um eval verde sobre
+/// a resposta de outro cenário — a única falha que este kit não pode ter.
+/// </para>
+/// <para>
+/// <b>Expiração NÃO é destrutiva.</b> A implementação da biblioteca apaga o diretório da chave
+/// ao ler uma entrada vencida — numa árvore commitada isso significa `git status` sujo e miss
+/// em massa num dia em que ninguém mexeu em nada. Aqui, entrada vencida devolve <c>null</c> e
+/// não toca em disco. O piso de TTL de um ano continua valendo como segunda linha de defesa:
+/// duas proteções para o mesmo tiro é barato quando o tiro apaga trabalho commitado.
+/// </para>
+/// <para>
+/// <b><see cref="ShortPathResponseCache.Refresh"/> é um no-op deliberado.</b> A validade é
+/// absoluta a partir da gravação, e não deslizante. Se <c>Refresh</c> reescrevesse o
+/// <c>entry.json</c>, uma LEITURA sujaria a árvore — e o invariante "um run offline não escreve
+/// um byte" cairia, junto com o canário que o cobra.
+/// </para>
+/// </remarks>
+public sealed class ShortPathResponseCacheProvider : IEvaluationResponseCacheProvider
+{
+    /// <summary>
+    /// Quantos caracteres do hash nomeiam o diretório da entrada.
+    /// </summary>
+    /// <remarks>
+    /// 16 hexadecimais = 64 bits. O número não precisa ser à prova de colisão sozinho: a
+    /// verificação da chave inteira no <c>entry.json</c> transforma qualquer colisão num miss.
+    /// Ele precisa apenas ser curto — e 16 derruba o pior caminho relativo de 225 para 145 (medido).
+    /// </remarks>
+    public const int KeyLength = 16;
+
+    /// <summary>Subdiretório que separa as entradas do carimbo, na raiz da árvore.</summary>
+    /// <remarks>
+    /// Mantido (a biblioteca também o usa) porque é ele que torna <see cref="ResetAsync"/>
+    /// trivialmente seguro: zerar a cache é apagar UM diretório, sem risco de levar o carimbo
+    /// junto. Custa seis caracteres e remove uma classe inteira de engano.
+    /// </remarks>
+    public const string EntriesDirectory = "cache";
+
+    private readonly string _root;
+    private readonly TimeSpan _timeToLive;
+    private readonly TimeProvider _clock;
+
+    /// <summary>Cria o provedor sobre uma raiz de cache.</summary>
+    /// <param name="storageRootPath">Raiz da árvore (a mesma que carrega o carimbo).</param>
+    /// <param name="timeToLive">Validade absoluta das entradas, contada da gravação.</param>
+    /// <param name="clock">Relógio injetado — a expiração é uma leitura de relógio.</param>
+    public ShortPathResponseCacheProvider(string storageRootPath, TimeSpan timeToLive, TimeProvider? clock = null)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(storageRootPath);
+
+        _root = storageRootPath;
+        _timeToLive = timeToLive;
+        _clock = clock ?? TimeProvider.System;
+    }
+
+    /// <summary>Onde as entradas vivem, dentro da raiz.</summary>
+    public string EntriesRoot => Path.Combine(_root, EntriesDirectory);
+
+    /// <inheritdoc />
+    public ValueTask<IDistributedCache> GetCacheAsync(
+        string scenarioName,
+        string iterationName,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(scenarioName);
+        ArgumentException.ThrowIfNullOrWhiteSpace(iterationName);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        IDistributedCache cache = new ShortPathResponseCache(
+            Path.Combine(EntriesRoot, scenarioName, iterationName), scenarioName, iterationName, _timeToLive, _clock);
+
+        return ValueTask.FromResult(cache);
+    }
+
+    /// <inheritdoc />
+    /// <remarks>Apaga TODAS as entradas e preserva o carimbo. Raiz ausente é sucesso: não há o que zerar.</remarks>
+    public ValueTask ResetAsync(CancellationToken cancellationToken = default)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+
+        if (Directory.Exists(EntriesRoot))
+        {
+            Directory.Delete(EntriesRoot, recursive: true);
+        }
+
+        return ValueTask.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// Este é o ÚNICO caminho que apaga entrada vencida, e ele só roda quando alguém o chama de
+    /// propósito. A leitura nunca apaga — ver as observações do tipo.
+    /// </remarks>
+    public ValueTask DeleteExpiredCacheEntriesAsync(CancellationToken cancellationToken = default)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+
+        if (!Directory.Exists(EntriesRoot))
+        {
+            return ValueTask.CompletedTask;
+        }
+
+        var now = _clock.GetUtcNow();
+        foreach (var entryFile in Directory.EnumerateFiles(EntriesRoot, ShortPathResponseCache.EntryFileName, SearchOption.AllDirectories))
+        {
+            var entry = ShortPathResponseCache.ReadEntry(entryFile);
+            if (entry is not null && entry.Expiration <= now)
+            {
+                Directory.Delete(Path.GetDirectoryName(entryFile)!, recursive: true);
+            }
+        }
+
+        return ValueTask.CompletedTask;
+    }
+}
+
+/// <summary>
+/// A cache de UM par (cenário, iteração). Ver <see cref="ShortPathResponseCacheProvider"/> para
+/// o porquê de ela existir.
+/// </summary>
+internal sealed class ShortPathResponseCache : IDistributedCache
+{
+    /// <summary>Metadados da entrada. Nome idêntico ao da biblioteca — o layout é o mesmo.</summary>
+    internal const string EntryFileName = "entry.json";
+
+    /// <summary>Payload cru da resposta. Nome idêntico ao da biblioteca.</summary>
+    internal const string ContentsFileName = "contents.data";
+
+    private static readonly JsonSerializerOptions Json = new() { WriteIndented = true };
+
+    private readonly string _directory;
+    private readonly string _scenarioName;
+    private readonly string _iterationName;
+    private readonly TimeSpan _timeToLive;
+    private readonly TimeProvider _clock;
+
+    internal ShortPathResponseCache(
+        string directory, string scenarioName, string iterationName, TimeSpan timeToLive, TimeProvider clock)
+    {
+        _directory = directory;
+        _scenarioName = scenarioName;
+        _iterationName = iterationName;
+        _timeToLive = timeToLive;
+        _clock = clock;
+    }
+
+    /// <summary>
+    /// O prefixo do hash que nomeia o diretório da entrada.
+    /// </summary>
+    /// <remarks>
+    /// A chave que a biblioteca entrega já é um hash hexadecimal; pegar o prefixo dela mantém o
+    /// nome CORRELACIONÁVEL com a chave real (é literalmente o começo dela), o que uma segunda
+    /// função de hash destruiria. Uma chave que não seja hexadecimal — improvável, mas não
+    /// impossível se a biblioteca mudar — é reduzida por SHA-256 antes de truncar, para que o
+    /// nome continue sendo um segmento de caminho válido em qualquer sistema de arquivos.
+    /// </remarks>
+    internal static string ShortKey(string key)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(key);
+
+        var usable = key.All(Uri.IsHexDigit)
+            ? key
+            : Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(key)));
+
+        return usable.Length <= ShortPathResponseCacheProvider.KeyLength
+            ? usable
+            : usable[..ShortPathResponseCacheProvider.KeyLength];
+    }
+
+    /// <inheritdoc />
+    public byte[]? Get(string key)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(key);
+
+        var dir = Path.Combine(_directory, ShortKey(key));
+        var entryPath = Path.Combine(dir, EntryFileName);
+        var contentsPath = Path.Combine(dir, ContentsFileName);
+
+        var entry = ReadEntry(entryPath);
+        if (entry is null || !File.Exists(contentsPath))
+        {
+            return null;
+        }
+
+        // A chave INTEIRA decide. O nome do diretório é um prefixo, e um prefixo pode colidir:
+        // sem esta comparação, a colisão devolveria a resposta de OUTRO cenário — a única falha
+        // que um eval não pode ter. Com ela, colisão vira miss, que é caro e visível.
+        if (!string.Equals(entry.Key, key, StringComparison.Ordinal))
+        {
+            return null;
+        }
+
+        // Vencida: devolve miss e NÃO apaga nada. Apagar durante a leitura é o que faz uma
+        // árvore commitada sumir sozinha e sujar o git status de quem só rodou os testes.
+        if (entry.Expiration <= _clock.GetUtcNow())
+        {
+            return null;
+        }
+
+        return File.ReadAllBytes(contentsPath);
+    }
+
+    /// <inheritdoc />
+    public Task<byte[]?> GetAsync(string key, CancellationToken token = default)
+    {
+        token.ThrowIfCancellationRequested();
+        return Task.FromResult(Get(key));
+    }
+
+    /// <inheritdoc />
+    public void Set(string key, byte[] value, DistributedCacheEntryOptions options)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(key);
+        ArgumentNullException.ThrowIfNull(value);
+
+        var dir = Path.Combine(_directory, ShortKey(key));
+        Directory.CreateDirectory(dir);
+
+        var now = _clock.GetUtcNow();
+        var entry = new CacheEntry
+        {
+            ScenarioName = _scenarioName,
+            IterationName = _iterationName,
+            Key = key,
+            Creation = now,
+            Expiration = now + _timeToLive,
+        };
+
+        File.WriteAllBytes(Path.Combine(dir, ContentsFileName), value);
+        // Quebras normalizadas para LF e uma quebra final: estes arquivos são COMMITADOS, e
+        // CRLF numa máquina com LF noutra é diff que não é diff.
+        File.WriteAllText(
+            Path.Combine(dir, EntryFileName),
+            JsonSerializer.Serialize(entry, Json).ReplaceLineEndings("\n") + "\n");
+    }
+
+    /// <inheritdoc />
+    public Task SetAsync(string key, byte[] value, DistributedCacheEntryOptions options, CancellationToken token = default)
+    {
+        token.ThrowIfCancellationRequested();
+        Set(key, value, options);
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// NO-OP deliberado. A validade é absoluta a partir da gravação, nunca deslizante: se este
+    /// método reescrevesse o <c>entry.json</c>, uma LEITURA passaria a escrever, e o invariante
+    /// "um run offline não muda um byte da árvore" — com o canário que o cobra — cairia junto.
+    /// </remarks>
+    public void Refresh(string key) { }
+
+    /// <inheritdoc />
+    public Task RefreshAsync(string key, CancellationToken token = default) => Task.CompletedTask;
+
+    /// <inheritdoc />
+    public void Remove(string key)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(key);
+
+        var dir = Path.Combine(_directory, ShortKey(key));
+        if (Directory.Exists(dir))
+        {
+            Directory.Delete(dir, recursive: true);
+        }
+    }
+
+    /// <inheritdoc />
+    public Task RemoveAsync(string key, CancellationToken token = default)
+    {
+        token.ThrowIfCancellationRequested();
+        Remove(key);
+        return Task.CompletedTask;
+    }
+
+    /// <summary>Lê o <c>entry.json</c>. Ausente ou ilegível devolve nulo — um miss, nunca uma exceção.</summary>
+    internal static CacheEntry? ReadEntry(string entryPath)
+    {
+        if (!File.Exists(entryPath))
+        {
+            return null;
+        }
+
+        try
+        {
+            return JsonSerializer.Deserialize<CacheEntry>(File.ReadAllText(entryPath), Json);
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+
+    /// <summary>O que o <c>entry.json</c> carrega. Sem caminho absoluto nenhum: a árvore é commitada.</summary>
+    internal sealed record CacheEntry
+    {
+        [JsonPropertyName("scenarioName")]
+        public required string ScenarioName { get; init; }
+
+        [JsonPropertyName("iterationName")]
+        public required string IterationName { get; init; }
+
+        /// <summary>A chave INTEIRA. É ela que torna o prefixo truncado seguro.</summary>
+        [JsonPropertyName("key")]
+        public required string Key { get; init; }
+
+        [JsonPropertyName("creation")]
+        public required DateTimeOffset Creation { get; init; }
+
+        [JsonPropertyName("expiration")]
+        public required DateTimeOffset Expiration { get; init; }
+    }
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Media/IMediaGenerator.cs

@@ -0,0 +1,42 @@
+namespace Morph.AiKit.Media;
+
+/// <summary>
+/// <b>O UNICO ponto de entrada publico da geracao de midia.</b>
+/// </summary>
+/// <remarks>
+/// <para>
+/// Leia as assinaturas: nenhuma delas devolve bytes, stream, <c>BinaryData</c> ou URL de
+/// provider. <see cref="EnqueueAsync"/> devolve um <see cref="MediaJobId"/> e
+/// <see cref="GetAsync"/> devolve o <see cref="MediaJob"/> com o estado dele. Isso e
+/// deliberado, e e o mecanismo — nao a explicacao — da regra dura de
+/// <c>ai-agents/media-pipeline.md</c>:
+/// </para>
+/// <para>
+/// <b>Nunca gere midia dentro de um turno de conversa.</b> Latencia documentada de ate 2
+/// minutos em imagem e de 11 s a 6 min em video, custo por chamada, e zero revisao possivel
+/// dentro do turno. O turno enfileira e confirma; a midia volta depois, revisada.
+/// </para>
+/// <para>
+/// O tipo que efetivamente produz bytes (<c>IMediaProvider</c> e os tres adaptadores de
+/// provider) e <c>internal</c> ao assembly, com <c>InternalsVisibleTo</c> liberando apenas
+/// <c>Morph.AiKit.Tests</c>. Um handler de mensagem no projeto consumidor <b>nao consegue
+/// nomear</b> esse tipo: o codigo nao compila. E a diferenca entre "o standard diz para nao
+/// fazer" e "o compilador recusa", e ha um teste de acessibilidade por reflexao que a
+/// mantem verdadeira.
+/// </para>
+/// </remarks>
+public interface IMediaGenerator
+{
+    /// <summary>
+    /// Aceita o pedido e devolve o id do job. <b>Nunca devolve bytes.</b>
+    /// </summary>
+    /// <remarks>
+    /// A chave de idempotencia de PEDIDO e consultada aqui, antes de qualquer chamada paga:
+    /// um pedido identico a outro ja atendido reusa o job existente em vez de pagar de
+    /// novo. O teto de custo tambem recusa aqui — depois da chamada, um alerta chega tarde.
+    /// </remarks>
+    Task<MediaResult<MediaJobId>> EnqueueAsync(MediaRequest request, CancellationToken cancellationToken = default);
+
+    /// <summary>O job, com estado, caminho e proveniencia. Job inexistente e recusa nomeada.</summary>
+    Task<MediaResult<MediaJob>> GetAsync(MediaJobId id, CancellationToken cancellationToken = default);
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Media/IMediaProvider.cs

@@ -0,0 +1,77 @@
+namespace Morph.AiKit.Media;
+
+/// <summary>
+/// O que PRODUZ BYTES. <b><c>internal</c> ao assembly, e e isso que prende a regra dura.</b>
+/// </summary>
+/// <remarks>
+/// <para>
+/// <c>ai-agents/media-pipeline.md</c> diz: <i>nunca gere midia dentro de um turno de
+/// conversa</i>. Uma frase num standard nao prende nada — o que prende e este modificador.
+/// </para>
+/// <para>
+/// Este tipo e os tres adaptadores de provider sao <c>internal</c>, com
+/// <c>InternalsVisibleTo</c> liberando apenas <c>Morph.AiKit.Tests</c>. Um handler de
+/// mensagem no projeto consumidor <b>nao consegue nomear</b> o tipo que produz bytes: o
+/// codigo nao compila. A unica superficie publica e
+/// <see cref="IMediaGenerator.EnqueueAsync"/>, que devolve um <see cref="MediaJobId"/>.
+/// </para>
+/// <para>
+/// Um teste de acessibilidade por reflexao (<c>MediaAccessibilityTests</c>) mantem esta
+/// afirmacao verdadeira: tornar o tipo publico derruba a suite. Um canario que ninguem viu
+/// morder pode ser o canario errado, entao a mutacao foi rodada.
+/// </para>
+/// </remarks>
+internal interface IMediaProvider
+{
+    /// <summary>Familia do SDK: <c>openai</c>, <c>google</c>.</summary>
+    string Provider { get; }
+
+    /// <summary>Se este adaptador atende esse tipo de midia.</summary>
+    bool Supports(MediaKind kind);
+
+    /// <summary>
+    /// Produz os bytes. Bloqueio de moderacao volta como
+    /// <see cref="MediaErrorCode.PolicyBlocked"/> — terminal, nunca retryable; falha
+    /// tecnica volta como <see cref="MediaErrorCode.ProviderFailure"/>.
+    /// </summary>
+    /// <param name="request">O pedido, ja validado.</param>
+    /// <param name="binding">
+    /// O alias resolvido. Viaja como parametro, e nao no construtor, porque um adaptador
+    /// atende N aliases do mesmo provider e uma instancia por alias multiplicaria clientes
+    /// sem nenhum ganho.
+    /// </param>
+    /// <param name="cancellationToken">—</param>
+    Task<MediaResult<MediaArtifact>> ProduceAsync(
+        MediaRequest request,
+        MediaAliasBinding binding,
+        CancellationToken cancellationToken);
+}
+
+/// <summary>
+/// Constroi os clientes de SDK dos providers de midia. <b>A costura do subsistema</b>: o
+/// unico ponto em que o kit toca um provider de verdade.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Publica de proposito, e pela mesma razao de <c>IProviderClientFactory</c>: e assim que a
+/// suite do kit roda <b>sem rede e sem chave de API</b> — em teste ninguem implementa esta
+/// interface, porque os testes usam um <c>IMediaProvider</c> fake e nunca chegam aqui.
+/// </para>
+/// <para>
+/// Devolver <c>null</c> significa "este provider nao e meu": o catalogo entao procura outro
+/// adaptador, e se nenhum atender, o job falha com motivo nomeado em vez de silenciosamente
+/// nao acontecer.
+/// </para>
+/// <para>
+/// <b>Quem descarta o cliente e o projeto</b>, que o construiu. O kit nao guarda cache
+/// propria de cliente — duas caches da mesma coisa e como um cliente vaza de um teste.
+/// </para>
+/// </remarks>
+public interface IMediaClientFactory
+{
+    /// <summary>O <c>ImageClient</c> do alias, ou nulo quando o provider nao e a OpenAI.</summary>
+    OpenAI.Images.ImageClient? CreateOpenAiImageClient(MediaAliasBinding binding);
+
+    /// <summary>O cliente do Google GenAI, ou nulo quando o provider nao e o Google.</summary>
+    Google.GenAI.Client? CreateGoogleClient(MediaAliasBinding binding);
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Media/MediaArtifact.cs

@@ -0,0 +1,28 @@
+namespace Morph.AiKit.Media;
+
+/// <summary>
+/// O que um provider produz: bytes, mais o que so o provider sabe sobre a geracao.
+/// </summary>
+/// <remarks>
+/// <b>Este tipo nunca sai pela superficie publica do subsistema.</b> Ele existe entre o
+/// <c>IMediaProvider</c> (internal) e o worker (internal); o que chega ao projeto e um
+/// <see cref="MediaJob"/> com caminho e hash. Se um handler consegue segurar um
+/// <see cref="MediaArtifact"/>, a regra dura de ai-agents/media-pipeline.md foi furada.
+/// </remarks>
+/// <param name="Kind">Imagem ou video.</param>
+/// <param name="MediaType">MIME dos bytes devolvidos pelo provider.</param>
+/// <param name="Bytes">O conteudo. Baixado JA, nunca uma URL guardada para depois.</param>
+/// <param name="RevisedPrompt">O prompt que o provider reescreveu, quando ele devolve um.</param>
+/// <param name="ResponseId">O id do lado do provider, para abrir chamado.</param>
+/// <param name="C2paPreserved">
+/// Se os metadados de proveniencia do provider sobreviveram ao caminho ate aqui. Falso
+/// quando o adaptador re-encodou os bytes — e um re-encode destrutivo apaga a credencial
+/// C2PA, que e a unica prova tecnica de origem que a imagem carregava.
+/// </param>
+internal sealed record MediaArtifact(
+    MediaKind Kind,
+    string MediaType,
+    ReadOnlyMemory<byte> Bytes,
+    string? RevisedPrompt,
+    string? ResponseId,
+    bool C2paPreserved);

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Media/MediaDisclosure.cs

@@ -0,0 +1,107 @@
+namespace Morph.AiKit.Media;
+
+/// <summary>
+/// A marcação "gerado/editado por IA" que acompanha a publicação.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Este tipo existe porque a afirmação estava só na prosa.</b> Antes dele,
+/// <see cref="MediaJobState.Published"/> dizia "publicado, com a marcacao aplicada" e
+/// <see cref="MediaPurpose.Marketing"/> dizia "marcacao visivel obrigatoria" — e um
+/// <c>grep</c> por label, watermark ou disclosure no kit inteiro voltava <b>vazio</b>. Três
+/// das quatro afirmações que a rubrica <c>media-claims</c> cobra de terceiros estavam presas
+/// por tipo ou por estado; a quarta, que é a obrigação legal, estava presa por nada.
+/// </para>
+/// <para>
+/// <b>O construtor é PRIVADO, e isso não é estilo.</b> A primeira versão deste tipo era um
+/// record POSICIONAL — e um record posicional gera um construtor <b>público</b>. A validação
+/// morava só em <see cref="Create"/>, então <c>new MediaDisclosure("", "", at)</c> compilava,
+/// era aceito, e publicava com rótulo vazio. Medido de um consumidor externo:
+/// <c>IsSuccess=True State=Published</c>, <c>Text='' Surface=''</c>. A prosa dizia "recusado na
+/// construção" em quatro superfícies; a construção não recusava nada. Uma marcação vazia é
+/// exatamente o campo preenchido "para passar" que este tipo existe para impedir, e agora é o
+/// <b>compilador</b> que fecha a porta — não a documentação. Mesma forma de
+/// <see cref="MediaReview"/>, três arquivos ao lado.
+/// </para>
+/// <para>
+/// <b>O que este tipo prova, exatamente:</b> que um job <b>não alcança</b>
+/// <see cref="MediaJobState.Published"/> sem uma marcação registrada e não-vazia, quando a
+/// finalidade a exige. É o mesmo mecanismo de <see cref="MediaJob.Approve"/> — uma transição
+/// que o código não tem, em vez de uma frase que alguém tem de lembrar.
+/// </para>
+/// <para>
+/// <b>O que ele NÃO prova, e é honesto dizer:</b> que o rótulo chegou aos olhos de alguém. A
+/// renderização é do aplicativo consumidor, e nenhum tipo em C# alcança um pixel. O que o kit
+/// garante é que a decisão foi tomada, com texto e superfície nomeados, e ficou gravada com o
+/// artefato — de modo que "esquecemos de marcar" deixa de ser um caminho silencioso e passa a
+/// ser uma recusa na publicação.
+/// </para>
+/// </remarks>
+public sealed record MediaDisclosure
+{
+    private MediaDisclosure(string text, string surface, DateTimeOffset appliedAt)
+    {
+        Text = text;
+        Surface = surface;
+        AppliedAt = appliedAt;
+    }
+
+    /// <summary>
+    /// O texto visível, por extenso. Em branco é recusado — e a recusa é presa pelo construtor
+    /// privado, não por convenção de chamada.
+    /// </summary>
+    public string Text { get; }
+
+    /// <summary>
+    /// ONDE o rótulo aparece — legenda, sobreposição, texto alternativo, ficha do produto. Sem
+    /// isto, "marcado" não diz se alguém consegue ver.
+    /// </summary>
+    public string Surface { get; }
+
+    /// <summary>Quando a marcação foi decidida.</summary>
+    public DateTimeOffset AppliedAt { get; }
+
+    /// <summary>
+    /// A ÚNICA forma de obter uma marcação. Recusa texto ou superfície em branco.
+    /// </summary>
+    /// <exception cref="ArgumentException">Texto ou superfície vazios.</exception>
+    public static MediaDisclosure Create(string text, string surface, DateTimeOffset appliedAt)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(text);
+        ArgumentException.ThrowIfNullOrWhiteSpace(surface);
+
+        return new MediaDisclosure(text, surface, appliedAt);
+    }
+}
+
+/// <summary>Política de marcação por finalidade. Escrita uma vez, aqui.</summary>
+public static class MediaPurposeExtensions
+{
+    /// <summary>
+    /// Se a finalidade exige marcação visível para publicar.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>Catálogo e marketing exigem; rascunho não publica.</b> A regra do art. 50 do AI Act
+    /// mira conteúdo que <i>possa parecer autêntico</i> sobre produto, pessoa ou lugar — e é
+    /// exatamente o que catálogo e peça de campanha são. A leitura conservadora é do standard
+    /// <c>ai-agents/media-pipeline.md</c>, seção Marcação, com a ressalva de fonte que ele
+    /// carrega: este predicado é uma decisão de desenho, não parecer jurídico.
+    /// </para>
+    /// <para>
+    /// Não confunda com <see cref="IsPublishable"/>: um rascunho não chega a publicar, então
+    /// a pergunta "precisa de marcação" nem se coloca para ele.
+    /// </para>
+    /// </remarks>
+    public static bool RequiresDisclosure(this MediaPurpose purpose)
+        => purpose is MediaPurpose.CatalogPhoto or MediaPurpose.Marketing;
+
+    /// <summary>
+    /// Se a finalidade pode chegar a <see cref="MediaJobState.Published"/>.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="MediaPurpose.Draft"/> se declara "nunca publicável" desde o primeiro dia — e
+    /// até este tipo existir, isso era só um comentário XML. Agora é uma recusa.
+    /// </remarks>
+    public static bool IsPublishable(this MediaPurpose purpose) => purpose != MediaPurpose.Draft;
+}