@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

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

@@ -5,56 +5,14 @@ using Microsoft.Extensions.AI.Evaluation.Reporting.Storage;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>O que uma execucao de cenario produziu.</summary>
-/// <param name="Scenario">A chave do cenario na cache (<c>{agente}/{tenant}/{nome}</c>).</param>
-/// <param name="Passed">Se TODAS as assercoes deterministicas se sustentaram.</param>
-/// <param name="Outcomes">Um veredito por assercao, na ordem do dataset.</param>
-/// <param name="Result">O resultado completo da biblioteca, com as metricas de juizo junto.</param>
 public sealed record EvalScenarioResult(
     string Scenario,
     bool Passed,
     IReadOnlyList<EvalAssertionOutcome> Outcomes,
     EvaluationResult Result);
 
-/// <summary>
-/// Monta a configuracao de eval com cache em disco de TTL explicito, roda os cenarios do
-/// dataset versionado e escreve o sumario que o CLI le.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>A montagem inteira existe para uma frase: com a cache quente, o eval roda sem
-/// credencial e sem rede.</b> O caminho e este — a biblioteca embrulha o cliente interno num
-/// cliente de cache; no HIT o interno nunca e invocado; em modo offline o interno e o
-/// <see cref="OfflineChatClient"/>, que recusa. Logo, ou tudo resolve pela cache, ou a suite
-/// fica vermelha nomeando o cenario que faltou. Nunca <c>skip</c>: gate verde sobre
-/// verificacao que nao aconteceu e o modo de falha que este harness mais paga para evitar.
-/// </para>
-/// <para>
-/// <b>Cache e resultados vivem em raizes DIFERENTES</b>, e isso e uma decisao, nao um
-/// detalhe: os resultados carregam latencia, uso de tokens e o flag de cache hit, todos
-/// nao-deterministicos. Numa raiz so, commitar a cache arrastaria os resultados junto e
-/// produziria diff em toda rodada, sem sinal nenhum. Separar por CONSTRUCAO (duas raizes) e
-/// mais forte que separar por <c>.gitignore</c>: uma regra de ignore dentro de um diretorio
-/// commitado e uma regra que a proxima pessoa remove sem entender.
-/// </para>
-/// <para>
-/// <b>Uma <c>ReportingConfiguration</c> por cenario</b>, e nao uma para a suite, porque as
-/// assercoes deterministicas SAO os avaliadores e elas mudam a cada cenario. A alternativa
-/// seria um avaliador com estado mutavel entre cenarios — barato de escrever e caro de
-/// depurar no dia em que dois cenarios rodarem fora de ordem.
-/// </para>
-/// </remarks>
 public sealed class EvalFixture : IAsyncDisposable
 {
-    /// <summary>
-    /// O nome do cenario em execucao, por indirecao.
-    /// </summary>
-    /// <remarks>
-    /// O <see cref="OfflineChatClient"/> e construido ANTES do fixture (ele e o cliente
-    /// interno dele) e precisa nomear, na mensagem de miss, o cenario que esta rodando
-    /// AGORA. Um nome capturado na construcao nomearia sempre o primeiro cenario, e a
-    /// mensagem mandaria o leitor investigar o cenario errado.
-    /// </remarks>
     private sealed class ScenarioCursor
     {
         public string Name { get; set; } = "(nenhum)";
@@ -87,33 +45,18 @@ public sealed class EvalFixture : IAsyncDisposable
         _resultStore = new DiskBasedResultStore(options.ResultsRoot);
     }
 
-    /// <summary>Nome da execucao no store de resultados. Estavel, porque os resultados nao se commitam.</summary>
     public const string ExecutionName = "morph-eval";
 
-    /// <summary>A configuracao efetiva desta execucao.</summary>
     public EvalCacheOptions Options { get; }
 
-    /// <summary>
-    /// O veredito do carimbo, apurado UMA vez na construcao — antes de avaliar qualquer
-    /// cenario. Nao faz sentido pagar o relogio de uma suite para descobrir no fim que a
-    /// cache nao servia.
-    /// </summary>
     public EvalCacheStampCheck StampCheck { get; }
 
-    /// <summary>
-    /// O cliente offline, quando o modo e <see cref="EvalMode.Offline"/>. E por ele que se
-    /// mede "zero invocacoes do cliente interno" — a prova de que nenhuma chamada paga foi
-    /// feita.
-    /// </summary>
     public OfflineChatClient? Offline => _offline;
 
-    /// <summary>Quantas vezes a cache falhou e a chamada desceu ao cliente interno.</summary>
     public int Misses => _offline?.Invocations ?? _counting?.Calls ?? 0;
 
-    /// <summary>Os resultados acumulados, na ordem em que os cenarios rodaram.</summary>
     public IReadOnlyList<EvalScenarioResult> Results => _results;
 
-    /// <summary>O sumario do que rodou ate agora.</summary>
     public EvalRunSummary Summary => new()
     {
         Scenarios = _results.Count,
@@ -128,15 +71,6 @@ public sealed class EvalFixture : IAsyncDisposable
         Failures = CollectFailures(),
     };
 
-    /// <summary>
-    /// Uma entrada por assercao REPROVADA, com o cenario que a carregava.
-    /// </summary>
-    /// <remarks>
-    /// Percorre as assercoes reprovadas, e nao os cenarios reprovados: o cenario diz ONDE, a
-    /// assercao diz O QUE. Um sumario que so contasse cenarios obrigaria quem le a reabrir o
-    /// dataset para descobrir qual regua quebrou — que e exatamente a investigacao que a
-    /// mensagem existe para dispensar.
-    /// </remarks>
     private IReadOnlyList<EvalFailureDetail> CollectFailures()
     {
         var failures = new List<EvalFailureDetail>();
@@ -145,10 +79,6 @@ public sealed class EvalFixture : IAsyncDisposable
         {
             var reproved = result.Outcomes.Where(o => !o.Passed).ToList();
 
-            // O cenario SEM assercao nenhuma reprova por vacuidade (ele nao cobra nada), e
-            // nesse caso nao existe outcome reprovado para nomear. Sem esta linha ele seria
-            // contado em `Failed` e invisivel em `Failures` — um numero sem frase, que e a
-            // metade exata do defeito que este tipo existe para fechar.
             if (reproved.Count == 0)
             {
                 failures.Add(new EvalFailureDetail(
@@ -169,20 +99,6 @@ public sealed class EvalFixture : IAsyncDisposable
         return failures;
     }
 
-    /// <summary>
-    /// Constroi o fixture a partir das variaveis que o CLI DITA.
-    /// </summary>
-    /// <remarks>
-    /// Fora do CLI um projeto pode montar <see cref="EvalCacheOptions"/> a mao e chamar
-    /// <see cref="Create"/>; as variaveis existem para que a MESMA suite seja executavel pelo
-    /// <c>verify</c> sem um segundo caminho de configuracao.
-    /// </remarks>
-    /// <param name="liveClient">
-    /// O cliente real. Obrigatorio em <see cref="EvalMode.Refresh"/> e
-    /// <see cref="EvalMode.Online"/>; ignorado em <see cref="EvalMode.Offline"/>.
-    /// </param>
-    /// <param name="qualityEvaluators">Avaliadores de juizo. Reportados, nunca decisivos.</param>
-    /// <param name="timeProvider">Relogio, para a checagem de pin no futuro.</param>
     public static EvalFixture FromEnvironment(
         IChatClient? liveClient = null,
         IEnumerable<IEvaluator>? qualityEvaluators = null,
@@ -198,8 +114,6 @@ public sealed class EvalFixture : IAsyncDisposable
             DatasetRoot = Environment.GetEnvironmentVariable("MORPH_EVAL_DATASET") ?? Path.Combine(beside, "eval-datasets"),
             ResultsRoot = Environment.GetEnvironmentVariable("MORPH_EVAL_RESULTS") ?? Path.Combine(beside, "eval-results"),
             Mode = ParseMode(Environment.GetEnvironmentVariable("MORPH_EVAL_MODE")),
-            // Explicito e longo: o default da biblioteca (14 dias) apagaria a arvore
-            // commitada durante uma leitura. Ver EvalCacheOptions.
             TimeToLive = TimeSpan.FromDays(3650),
             ProviderName = Environment.GetEnvironmentVariable("MORPH_EVAL_PROVIDER") ?? "morph-eval",
             DefaultModelId = Environment.GetEnvironmentVariable("MORPH_EVAL_MODEL"),
@@ -211,9 +125,6 @@ public sealed class EvalFixture : IAsyncDisposable
         return Create(options, liveClient, qualityEvaluators, timeProvider);
     }
 
-    /// <summary>Constroi o fixture a partir de opcoes explicitas.</summary>
-    /// <exception cref="ArgumentOutOfRangeException">TTL abaixo do piso — ver <see cref="EvalCacheOptions.MinimumTimeToLive"/>.</exception>
-    /// <exception cref="InvalidOperationException">Carimbo ausente ou divergente em modo de leitura; ou modo de escrita sem cliente real.</exception>
     public static EvalFixture Create(
         EvalCacheOptions options,
         IChatClient? liveClient = null,
@@ -237,8 +148,7 @@ public sealed class EvalFixture : IAsyncDisposable
         var clock = timeProvider ?? TimeProvider.System;
         IReadOnlyList<IEvaluator> quality = qualityEvaluators is null ? [] : [.. qualityEvaluators];
 
-        // O carimbo so e COBRADO nos modos que LEEM a cache. Em Refresh a arvore esta sendo
-        // (re)escrita — cobrar carimbo ali tornaria impossivel criar a primeira cache.
+        // Em Refresh a arvore esta sendo reescrita: cobrar carimbo impediria gravar a primeira cache.
         var stampCheck = options.Mode == EvalMode.Refresh || options.Pin is null
             ? new EvalCacheStampCheck(
                 EvalStampVerdict.Ok,
@@ -278,10 +188,6 @@ public sealed class EvalFixture : IAsyncDisposable
         return new EvalFixture(options, stampCheck, cursor, inner, offline, counting, quality);
     }
 
-    /// <summary>
-    /// Roda TODOS os cenarios do dataset e escreve o sumario, quando ha caminho para ele.
-    /// </summary>
-    /// <exception cref="InvalidOperationException">Dataset sem nenhum cenario — uma suite de eval que avalia zero cenarios e sai verde e um guardrail inerte.</exception>
     public async Task<EvalRunSummary> RunAllAsync(CancellationToken cancellationToken = default)
     {
         var scenarios = EvalScenario.LoadAll(Options.DatasetRoot);
@@ -293,9 +199,7 @@ public sealed class EvalFixture : IAsyncDisposable
               + "que este kit existe para nao produzir.");
         }
 
-        // Em Refresh a arvore inteira e zerada antes de regravar: uma regravacao parcial
-        // deixaria entradas de uma versao antiga convivendo com entradas novas, e a proxima
-        // leitura offline nao teria como saber quais sao quais.
+        // Zera antes de regravar: entradas de versoes diferentes nao podem conviver na arvore.
         if (Options.Mode == EvalMode.Refresh)
         {
             try
@@ -305,12 +209,7 @@ public sealed class EvalFixture : IAsyncDisposable
             }
             catch (DirectoryNotFoundException)
             {
-                // MEDIDO na v10.9.0: ResetAsync chama Directory.Delete no subdiretorio de
-                // cache e LANCA quando ele ainda nao existe — o caso da PRIMEIRA gravacao.
-                // "Nao ha o que zerar" e sucesso, nao falha. Capturado aqui, e nao evitado
-                // com um Directory.Exists sobre o layout interno da biblioteca: repetir o
-                // nome do subdiretorio dela aqui seria uma segunda verdade sobre onde a
-                // cache mora.
+                // Raiz ausente na primeira gravacao: nada a zerar.
             }
         }
 
@@ -339,7 +238,6 @@ public sealed class EvalFixture : IAsyncDisposable
         return summary;
     }
 
-    /// <summary>Roda UM cenario: resolve a resposta (cache ou cliente interno) e aplica os avaliadores.</summary>
     public async Task<EvalScenarioResult> RunAsync(EvalScenario scenario, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(scenario);
@@ -378,11 +276,9 @@ public sealed class EvalFixture : IAsyncDisposable
             outcomes.Add(assertion.Evaluate(response));
         }
 
-        // Um cenario SEM assercao deterministica nao passa: ele nao cobra nada. Deixa-lo
-        // verde por vacuidade e o mesmo defeito de um teste vazio — e aqui ele seria pior,
-        // porque o cenario apareceria na contagem como se tivesse verificado algo.
         var scenarioResult = new EvalScenarioResult(
             scenario.CacheKey,
+            // Sem assercao o cenario reprova: verde por vacuidade contaria como verificado.
             outcomes.Count > 0 && outcomes.All(o => o.Passed),
             outcomes,
             result);
@@ -391,7 +287,6 @@ public sealed class EvalFixture : IAsyncDisposable
         return scenarioResult;
     }
 
-    /// <inheritdoc />
     public ValueTask DisposeAsync()
     {
         _inner.Dispose();

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

@@ -1,32 +1,10 @@
 namespace Morph.AiKit.Evals;
 
-/// <summary>
-/// De onde a resposta do modelo pode vir nesta execucao de eval.
-/// </summary>
-/// <remarks>
-/// A distincao existe porque as tres situacoes tem custos diferentes em DINHEIRO e em
-/// confianca, e um enum de dois valores ("usa cache" / "nao usa") esconderia a do meio.
-/// </remarks>
 public enum EvalMode
 {
-    /// <summary>
-    /// So a cache. Um miss e falha nomeada, nunca uma chamada de rede — e nunca um
-    /// <c>skip</c>: gate verde sobre verificacao que nao aconteceu e o modo de falha que
-    /// este harness mais paga para evitar. E o modo do CI.
-    /// </summary>
     Offline = 0,
 
-    /// <summary>
-    /// Reexecuta TODOS os cenarios contra o provider e regrava a arvore de cache. Exige
-    /// credencial e nunca acontece implicitamente: uma regravacao automatica e uma chamada
-    /// paga que ninguem pediu.
-    /// </summary>
     Refresh = 1,
 
-    /// <summary>
-    /// Cache primeiro, provider no miss. E o modo de quem esta escrevendo cenario novo na
-    /// propria maquina: paga so pelo que falta, e o resultado sai marcado como
-    /// <c>cold</c> com aviso de que a arvore mudou e precisa ser commitada.
-    /// </summary>
     Online = 2,
 }

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

@@ -3,44 +3,9 @@ using Microsoft.Extensions.AI.Evaluation.Quality;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>
-/// Os avaliadores de JUIZO que o kit considera utilizaveis, e a fronteira que os separa dos
-/// experimentais.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Eles nunca decidem.</b> O veredito de um cenario sai das <see cref="EvalAssertion"/>
-/// deterministicas; o que sai daqui e METRICA REPORTADA. Um juizo de LLM que reprovasse
-/// sozinho reintroduziria a variancia que faz suites de eval serem desligadas do CI — e um
-/// no de eval desligado nao verifica nada.
-/// </para>
-/// <para>
-/// <b>Por que a lista e curta.</b> Dois dos quatro avaliadores que o plano desta feature
-/// listava como estaveis carregam <c>[Experimental("AIEVAL001")]</c> na versao pinada:
-/// <c>TaskAdherenceEvaluator</c> e <c>ToolCallAccuracyEvaluator</c>. Sob
-/// <c>TreatWarningsAsErrors</c>, usa-los exige suprimir um diagnostico — uma decisao
-/// consciente de quem adota o kit, jamais um efeito colateral de chamar um metodo chamado
-/// "Stable". Medido por reflexao sobre <c>Microsoft.Extensions.AI.Evaluation.Quality</c>
-/// 10.9.0, e pinado pelo teste <c>WhichQualityEvaluatorsAreExperimentalIsMEASURED</c>.
-/// </para>
-/// <para>
-/// <b>E por que este tipo existe.</b> Sem uma unica referencia em <c>src/</c>, o pacote
-/// <c>.Quality</c> teria apenas contrato de VERSAO (o restore, NU1102) e um rename de API
-/// nele nao reprovaria PR nenhuma. Com o <c>using</c> real acima, ele passa a ter cobertura
-/// de compilacao — que e o nivel de garantia que o kit promete para a familia de Evaluation.
-/// </para>
-/// </remarks>
 public static class EvalQualityEvaluators
 {
-    /// <summary>
-    /// Os avaliadores de qualidade NAO experimentais da versao pinada, prontos para
-    /// <see cref="EvalFixture.Create"/>.
-    /// </summary>
-    /// <remarks>
-    /// Uma lista nova a cada chamada: os avaliadores sao passados adiante e guardados por uma
-    /// <c>ReportingConfiguration</c>, e um array compartilhado seria estado global disfarcado
-    /// de conveniencia.
-    /// </remarks>
+    // TaskAdherence e ToolCallAccuracy ficam fora: sao [Experimental("AIEVAL001")] no Quality 10.9.0.
     public static IReadOnlyList<IEvaluator> Stable() =>
     [
         new RelevanceEvaluator(),

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

@@ -4,73 +4,21 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>
-/// Um cenario de eval: as mensagens que vao ao modelo e as propriedades que a resposta tem
-/// de ter.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>O dataset e versionado e vive em disco</b>, organizado como
-/// <c>{agente}/{tenant}/{cenario}.json</c>. Os dois primeiros segmentos existem porque a
-/// pergunta util quase nunca e "o produto regrediu?", e sim "o agente X regrediu para o
-/// tenant Y?" — e um dataset plano nao consegue responder isso sem convencao de nome.
-/// </para>
-/// <para>
-/// <b>Dado real de tenant e proibido aqui.</b> A cache guarda mensagens INTEIRAS e e
-/// commitada: um segredo que entre no dataset entra no git. O fixture so le cenario deste
-/// diretorio versionado — nunca de banco, nunca de variavel de ambiente.
-/// </para>
-/// </remarks>
 public sealed record EvalScenario
 {
-    /// <summary>Primeiro segmento do caminho no dataset.</summary>
     public required string Agent { get; init; }
 
-    /// <summary>Segundo segmento do caminho no dataset.</summary>
     public required string Tenant { get; init; }
 
-    /// <summary>
-    /// Nome do arquivo, sem extensao. Vira o <c>scenarioName</c> da cache, e por isso e o
-    /// que aparece na mensagem de miss.
-    /// </summary>
     public required string Name { get; init; }
 
-    /// <summary>As mensagens enviadas ao modelo, na ordem.</summary>
     public required IReadOnlyList<ChatMessage> Messages { get; init; }
 
-    /// <summary>As assercoes deterministicas que decidem pass/fail deste cenario.</summary>
     public IReadOnlyList<EvalAssertion> Assertions { get; init; } = [];
 
-    /// <summary>
-    /// Identidade do cenario dentro da cache: <c>{agente}.{tenant}.{nome}</c>.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// Qualificado, e nao so <see cref="Name"/>, porque dois tenants tem cenarios com o
-    /// mesmo nome de proposito ("saudacao", "handoff") — e uma chave de cache que os
-    /// confundisse devolveria a resposta de um tenant para o outro.
-    /// </para>
-    /// <para>
-    /// <b>O separador e ponto, e nao barra, por uma MEDICAO.</b> A primeira versao usava
-    /// barra, na suposicao de que a biblioteca aninharia o nome do cenario em diretorios. Ela
-    /// nao aninha: <c>PathValidation.ValidatePathSegment</c> recusa o nome com
-    /// <c>ArgumentException: 'scenarioName' contains invalid path characters or directory
-    /// traversal sequences</c> — o nome do cenario e UM segmento de caminho, sempre. Medido
-    /// na v10.9.0 contra o SDK .NET 10.
-    /// </para>
-    /// </remarks>
+    // Ponto, nao barra: a biblioteca exige que o nome do cenario seja UM segmento de caminho (10.9.0).
     public string CacheKey => $"{Agent}.{Tenant}.{Name}";
 
-    /// <summary>
-    /// Le TODOS os cenarios de um dataset, em ordem estavel (ordinal por caminho).
-    /// </summary>
-    /// <remarks>
-    /// Ordem estavel importa mais do que parece: e ela que faz duas maquinas gravarem a
-    /// mesma arvore de cache e produzirem o mesmo diff. Uma enumeracao dependente do
-    /// sistema de arquivos e um diff que muda sozinho.
-    /// </remarks>
-    /// <param name="datasetRoot">Raiz do dataset versionado.</param>
-    /// <exception cref="DirectoryNotFoundException">Quando a raiz nao existe — declarar um dataset ausente e erro de config, nao um dataset vazio.</exception>
     public static IReadOnlyList<EvalScenario> LoadAll(string datasetRoot)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(datasetRoot);
@@ -85,6 +33,7 @@ public sealed record EvalScenario
 
         var files = Directory
             .EnumerateFiles(datasetRoot, "*.json", SearchOption.AllDirectories)
+            // Ordem ordinal: duas maquinas precisam gravar a mesma arvore de cache.
             .OrderBy(p => p.Replace('\\', '/'), StringComparer.Ordinal)
             .ToList();
 
@@ -97,7 +46,6 @@ public sealed record EvalScenario
         return scenarios;
     }
 
-    /// <summary>Le um cenario, derivando agente e tenant do caminho relativo a raiz.</summary>
     public static EvalScenario Load(string datasetRoot, string file)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(datasetRoot);
@@ -126,9 +74,6 @@ public sealed record EvalScenario
         for (var i = 0; i < (dto.Assertions?.Count ?? 0); i++)
         {
             var raw = dto.Assertions![i];
-            // Nome default derivado do indice, e unicidade COBRADA: a biblioteca indexa
-            // metricas por nome, e um nome repetido faria a segunda assercao sobrescrever a
-            // primeira — um cenario que parece cobrar duas propriedades cobrando uma.
             var name = string.IsNullOrWhiteSpace(raw.Name) ? $"{raw.Kind}-{i + 1}" : raw.Name!;
             if (!used.Add(name))
             {

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