@polymorphism-tech/morph-spec 8.38.0 → 8.41.0

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

@@ -3,128 +3,55 @@ using System.Text.Json.Serialization;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>Estado da arvore de cache nesta execucao, como o sumario o reporta.</summary>
 public static class EvalCacheState
 {
-    /// <summary>Todos os cenarios resolveram pela cache. Nenhuma chamada ao provider.</summary>
     public const string Warm = "warm";
 
-    /// <summary>Ao menos um cenario foi ao provider — a arvore mudou e precisa ser commitada.</summary>
     public const string Cold = "cold";
 }
 
-/// <summary>Uma falha de eval, com nome — cenario, assercao e o motivo literal.</summary>
-/// <remarks>
-/// <para>
-/// <b>Por que o sumario carrega isto, e nao so contadores.</b> Medido: degradar a resposta em
-/// cache deixava a suite vermelha (correto) com a mensagem <c>Expected 0, Actual 1</c> —
-/// verdadeira e inutil. Nada a jusante conseguia dizer QUAL cenario caiu nem por que, porque a
-/// informacao morria dentro do fixture.
-/// </para>
-/// <para>
-/// A rubrica <c>eval-de-modelo.md</c> exige, na banda 9-10, "derrubando o cenario e
-/// NOMEANDO-O", e da como exemplo <c>eval-fail: triagem.acme.a-saudacao</c>. Sem este tipo a
-/// propria rubrica seria inexequivel — o que e pior do que nao ter rubrica, porque parece
-/// coberto.
-/// </para>
-/// </remarks>
-/// <param name="Scenario">A chave do cenario (<c>{agente}.{tenant}.{nome}</c>).</param>
-/// <param name="Assertion">O nome da assercao que reprovou.</param>
-/// <param name="Kind">A regua usada, para distinguir duas assercoes homonimas de tipos distintos.</param>
-/// <param name="Reason">O motivo literal produzido pela assercao.</param>
 public sealed record EvalFailureDetail(
     [property: JsonPropertyName("scenario")] string Scenario,
     [property: JsonPropertyName("assertion")] string Assertion,
     [property: JsonPropertyName("kind")] string Kind,
     [property: JsonPropertyName("reason")] string Reason)
 {
-    /// <summary>Uma linha legivel, no formato que a rubrica cita.</summary>
     public override string ToString()
         => $"eval-fail: {Scenario} — {Assertion} ({Kind}): {Reason}";
 }
 
-/// <summary>
-/// O sumario que o fixture escreve no fim da suite, e que o CLI le.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que ARQUIVO e nao uma linha marcada no stdout.</b> O runner de teste captura a
-/// saida de console por teste, e o que chega ao stdout do processo depende da configuracao
-/// do runner e do logger. Um contrato que quebra quando alguem liga um logger e um contrato
-/// ruim — e a falha seria SILENCIOSA (sumario ausente, contagem desconhecida, no verde pelo
-/// codigo de saida). O arquivo tem outra virtude: quem escolhe o caminho e o CLI, entao dois
-/// nos de eval no mesmo <c>verify</c> nao colidem.
-/// </para>
-/// <para>
-/// <b>Do outro lado, o leitor trata sumario ausente ou ilegivel como DESCONHECIDO, jamais
-/// como zero.</b> Um sumario que nao parseia nao pode fabricar <c>scenarios: 0</c> e
-/// transformar uma baseline em queda inventada.
-/// </para>
-/// </remarks>
 public sealed record EvalRunSummary
 {
-    /// <summary>Quantos cenarios foram avaliados.</summary>
     [JsonPropertyName("scenarios")]
     public required int Scenarios { get; init; }
 
-    /// <summary>Quantos passaram em TODAS as suas assercoes deterministicas.</summary>
     [JsonPropertyName("passed")]
     public required int Passed { get; init; }
 
-    /// <summary>Quantos falharam em ao menos uma assercao deterministica.</summary>
     [JsonPropertyName("failed")]
     public required int Failed { get; init; }
 
-    /// <summary><see cref="EvalCacheState.Warm"/> ou <see cref="EvalCacheState.Cold"/>.</summary>
     [JsonPropertyName("cache")]
     public required string Cache { get; init; }
 
-    /// <summary>Veredito do carimbo, em minusculas (<c>ok</c>, <c>missing</c>, ...).</summary>
     [JsonPropertyName("stamp")]
     public required string Stamp { get; init; }
 
-    /// <summary>
-    /// Quantas vezes a cache falhou e a chamada desceu ao cliente interno. Em modo offline
-    /// com cache quente e ZERO — e esse zero e a prova de que nenhuma chamada paga foi feita.
-    /// </summary>
     [JsonPropertyName("misses")]
     public required int Misses { get; init; }
 
-    /// <summary>O <c>ProviderName</c> usado, o mesmo que entrou na chave.</summary>
     [JsonPropertyName("provider")]
     public required string Provider { get; init; }
 
-    /// <summary>O <c>DefaultModelId</c> usado, o mesmo que entrou na chave.</summary>
     [JsonPropertyName("model")]
     public string? Model { get; init; }
 
-    /// <summary>
-    /// Metricas de JUIZO (avaliadores de qualidade), nome para valor. Reportadas, nunca
-    /// decisivas: com a cache quente elas sao deterministicas, mas a variancia volta na
-    /// regravacao, e um gate que dependesse disso nasceria destinado a ser desligado.
-    /// </summary>
     [JsonPropertyName("quality")]
     public IReadOnlyDictionary<string, double> Quality { get; init; } = new Dictionary<string, double>(StringComparer.Ordinal);
 
-    /// <summary>
-    /// As falhas, uma por assercao reprovada, com nome. Vazia num run verde.
-    /// </summary>
-    /// <remarks>
-    /// Lista, e nao um booleano ou um contador, porque um cenario pode quebrar em mais de uma
-    /// assercao e as duas informam coisas diferentes: uma resposta vazia derruba
-    /// <c>Contains</c> E <c>JsonHasKey</c>, e saber disso e a diferenca entre "o prompt mudou"
-    /// e "o modelo parou de responder".
-    /// </remarks>
     [JsonPropertyName("failures")]
     public IReadOnlyList<EvalFailureDetail> Failures { get; init; } = [];
 
-    /// <summary>
-    /// As falhas em texto, uma por linha — a mensagem que um teste ou o CLI mostra.
-    /// </summary>
-    /// <remarks>
-    /// Devolve frase propria quando nao ha falha alguma, em vez de string vazia: uma mensagem
-    /// de assercao vazia e indistinguivel de uma mensagem que ninguem preencheu.
-    /// </remarks>
     public string DescribeFailures()
         => Failures.Count == 0
             ? "nenhuma falha de eval registrada"
@@ -132,7 +59,6 @@ public sealed record EvalRunSummary
 
     private static readonly JsonSerializerOptions Json = new() { WriteIndented = true };
 
-    /// <summary>Grava o sumario. Cria o diretorio se preciso; sobrescreve se ja existe.</summary>
     public void WriteTo(string path)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(path);
@@ -146,7 +72,6 @@ public sealed record EvalRunSummary
         File.WriteAllText(path, JsonSerializer.Serialize(this, Json));
     }
 
-    /// <summary>Le um sumario gravado. Devolve nulo para arquivo ausente ou ilegivel — DESCONHECIDO, jamais zero.</summary>
     public static EvalRunSummary? ReadFrom(string path)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(path);

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);
 }