@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

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

@@ -2,39 +2,6 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>
-/// O <see cref="IChatClient"/> que RECUSA no miss: a peca que torna possivel rodar evals no
-/// CI sem uma unica credencial.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Onde ele fica.</b> A biblioteca de Evaluation embrulha o cliente que recebe num
-/// cliente de cache. No HIT, o cliente interno nunca e invocado. No MISS, a chamada desce
-/// para o interno — e o interno, aqui, e este. Logo: com a cache quente ele nao e chamado
-/// nenhuma vez, e quando e chamado a resposta certa e "faltou cenario na cache", nao uma
-/// chamada de rede.
-/// </para>
-/// <para>
-/// <b>Por que ele replica <c>ProviderName</c> e <c>DefaultModelId</c>.</b> Esses dois
-/// campos do <see cref="ChatClientMetadata"/> entram na chave de cache. Se o cliente
-/// offline se apresentasse com outro nome, a chave computada na leitura seria outra e TODO
-/// cenario daria miss — uma cache quente indistinguivel de uma cache vazia. Eles sao
-/// parametros, e nao constantes, exatamente porque tem de reproduzir o run que GRAVOU.
-/// </para>
-/// <para>
-/// <b><see cref="ChatClientMetadata.ProviderUri"/> e deliberadamente nulo.</b> O endpoint
-/// NAO entra na chave — medido contra a v10.9.0, contra o que a documentacao afirma. E essa
-/// ausencia que permite ao cliente offline nao ter endpoint nenhum: ele nao tem para onde
-/// ligar, e nao precisa ter.
-/// </para>
-/// <para>
-/// <b><see cref="Invocations"/> e a prova, e ela e um contador, nao um sniffer.</b> "Zero
-/// chamadas de rede" nao se mede sem instrumentar a rede; "zero invocacoes do cliente
-/// interno" se mede aqui, e e suficiente porque o cliente interno e o UNICO caminho para a
-/// rede nesta montagem. O contador sobe ANTES do lancamento, para que uma tentativa
-/// interrompida ainda apareca.
-/// </para>
-/// </remarks>
 public sealed class OfflineChatClient : IChatClient
 {
     private readonly Lock _gate = new();
@@ -43,18 +10,7 @@ public sealed class OfflineChatClient : IChatClient
     private readonly string _envFile;
     private int _invocations;
 
-    /// <summary>
-    /// Cria o cliente offline replicando a identidade do run que gravou a cache.
-    /// </summary>
-    /// <param name="providerName">Mesmo <c>ProviderName</c> do run que gravou. Entra na chave.</param>
-    /// <param name="defaultModelId">Mesmo <c>DefaultModelId</c> do run que gravou. Entra na chave.</param>
-    /// <param name="cachePath">Raiz da arvore de cache, so para a mensagem de miss.</param>
-    /// <param name="envFile">Arquivo de credencial esperado, so para a mensagem de miss.</param>
-    /// <param name="currentScenario">
-    /// Le o nome do cenario em execucao no momento da chamada. E uma funcao, e nao um
-    /// valor, porque um fixture roda N cenarios com o MESMO cliente: um nome capturado na
-    /// construcao nomearia sempre o primeiro.
-    /// </param>
+    // ProviderName e DefaultModelId entram na chave de cache: tem de reproduzir o run que gravou.
     public OfflineChatClient(
         string providerName,
         string? defaultModelId,
@@ -74,36 +30,27 @@ public sealed class OfflineChatClient : IChatClient
         _currentScenario = currentScenario;
     }
 
-    /// <summary>O <c>ProviderName</c> replicado — o mesmo que gravou a cache.</summary>
     public string ProviderName { get; }
 
-    /// <summary>O <c>DefaultModelId</c> replicado — o mesmo que gravou a cache.</summary>
     public string? DefaultModelId { get; }
 
-    /// <summary>
-    /// Quantas vezes a cache falhou e a chamada desceu ate aqui. Num run com a cache quente
-    /// e ZERO, e essa e a prova de que nenhuma chamada paga foi feita.
-    /// </summary>
     public int Invocations
     {
         get { lock (_gate) { return _invocations; } }
     }
 
-    /// <inheritdoc />
     public Task<ChatResponse> GetResponseAsync(
         IEnumerable<ChatMessage> messages,
         ChatOptions? options = null,
         CancellationToken cancellationToken = default)
         => throw Miss();
 
-    /// <inheritdoc />
     public IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
         IEnumerable<ChatMessage> messages,
         ChatOptions? options = null,
         CancellationToken cancellationToken = default)
         => throw Miss();
 
-    /// <inheritdoc />
     public object? GetService(Type serviceType, object? serviceKey = null)
     {
         ArgumentNullException.ThrowIfNull(serviceType);
@@ -115,19 +62,15 @@ public sealed class OfflineChatClient : IChatClient
 
         if (serviceType == typeof(ChatClientMetadata))
         {
-            // providerUri nulo de proposito: o endpoint nao entra na chave de cache, e um
-            // cliente que nunca liga para lugar nenhum nao deve anunciar um destino.
+            // O endpoint nao entra na chave de cache (medido na 10.9.0), entao o cliente offline nao anuncia nenhum.
             return new ChatClientMetadata(ProviderName, providerUri: null, DefaultModelId);
         }
 
         return serviceType.IsInstanceOfType(this) ? this : null;
     }
 
-    /// <inheritdoc />
     public void Dispose()
     {
-        // Nada a liberar: este cliente nao abre socket, nao le ambiente e nao guarda estado
-        // fora do contador. E o ponto.
     }
 
     private EvalCacheMissException Miss()

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

@@ -7,79 +7,17 @@ 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>
+// O DiskBasedResponseCacheProvider da biblioteca nomeia a entrada com o hash inteiro (96 chars) e estoura o MAX_PATH do Windows.
 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);
@@ -89,10 +27,8 @@ public sealed class ShortPathResponseCacheProvider : IEvaluationResponseCachePro
         _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,
@@ -108,8 +44,6 @@ public sealed class ShortPathResponseCacheProvider : IEvaluationResponseCachePro
         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();
@@ -122,11 +56,6 @@ public sealed class ShortPathResponseCacheProvider : IEvaluationResponseCachePro
         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();
@@ -150,16 +79,10 @@ public sealed class ShortPathResponseCacheProvider : IEvaluationResponseCachePro
     }
 }
 
-/// <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 };
@@ -180,16 +103,6 @@ internal sealed class ShortPathResponseCache : IDistributedCache
         _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);
@@ -203,7 +116,6 @@ internal sealed class ShortPathResponseCache : IDistributedCache
             : usable[..ShortPathResponseCacheProvider.KeyLength];
     }
 
-    /// <inheritdoc />
     public byte[]? Get(string key)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(key);
@@ -218,16 +130,13 @@ internal sealed class ShortPathResponseCache : IDistributedCache
             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.
+        // O diretorio e so um prefixo do hash: a chave inteira decide, e colisao vira miss em vez da resposta de outro cenario.
         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.
+        // Vencida nao apaga, ao contrario da biblioteca: a arvore e commitada e uma leitura nao pode sujar o git status.
         if (entry.Expiration <= _clock.GetUtcNow())
         {
             return null;
@@ -236,14 +145,12 @@ internal sealed class ShortPathResponseCache : IDistributedCache
         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);
@@ -263,14 +170,11 @@ internal sealed class ShortPathResponseCache : IDistributedCache
         };
 
         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();
@@ -278,18 +182,11 @@ internal sealed class ShortPathResponseCache : IDistributedCache
         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>
+    // No-op: a validade e absoluta, e reescrever o entry.json faria uma leitura escrever na arvore commitada.
     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);
@@ -301,7 +198,6 @@ internal sealed class ShortPathResponseCache : IDistributedCache
         }
     }
 
-    /// <inheritdoc />
     public Task RemoveAsync(string key, CancellationToken token = default)
     {
         token.ThrowIfCancellationRequested();
@@ -309,7 +205,6 @@ internal sealed class ShortPathResponseCache : IDistributedCache
         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))
@@ -327,7 +222,6 @@ internal sealed class ShortPathResponseCache : IDistributedCache
         }
     }
 
-    /// <summary>O que o <c>entry.json</c> carrega. Sem caminho absoluto nenhum: a árvore é commitada.</summary>
     internal sealed record CacheEntry
     {
         [JsonPropertyName("scenarioName")]
@@ -336,7 +230,6 @@ internal sealed class ShortPathResponseCache : IDistributedCache
         [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; }
 

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

@@ -1,42 +1,8 @@
 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

@@ -1,77 +1,21 @@
 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 e o que impede um handler de gerar midia dentro do turno de conversa; MediaAccessibilityTests cobra.
 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

@@ -1,24 +1,5 @@
 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,

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

@@ -1,44 +1,8 @@
 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
 {
+    // Privado de proposito: um record posicional geraria construtor publico que pula a validacao de Create.
     private MediaDisclosure(string text, string surface, DateTimeOffset appliedAt)
     {
         Text = text;
@@ -46,25 +10,12 @@ public sealed record MediaDisclosure
         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);
@@ -74,34 +25,11 @@ public sealed record MediaDisclosure
     }
 }
 
-/// <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>
+    // AI Act art. 50, na leitura conservadora de ai-agents/media-pipeline.md (decisao de desenho, nao parecer juridico).
     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;
 }