@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Rag/DeltaIngest.cs

@@ -1,22 +1,5 @@
 namespace Morph.AiKit.Rag;
 
-/// <summary>
-/// Erro de <b>entrada</b> do <see cref="DeltaIngest"/>: a mesma lookup-key apareceu duas
-/// vezes na mesma remessa.
-/// </summary>
-/// <remarks>
-/// <para>
-/// Nao e fluxo de controle e nao e recuperavel no lugar: com a chave repetida, "o que esta
-/// no acervo" deixa de ter resposta unica e o plano vira nao-deterministico — qual dos dois
-/// itens venceu passa a depender da ordem de enumeracao. Silenciar (ficar com o ultimo)
-/// gravaria um dos dois ao acaso; deduplicar por conta propria esconderia um defeito da
-/// origem, que e onde ele tem conserto.
-/// </para>
-/// <para>
-/// Os dois indices vao na excecao porque "chave X duplicada" manda procurar num corpus de
-/// milhares; "posicoes 12 e 4.871" manda olhar duas linhas.
-/// </para>
-/// </remarks>
 public sealed class DuplicateLookupKeyException : ArgumentException
 {
     internal DuplicateLookupKeyException(string lookupKey, int firstIndex, int duplicateIndex, string paramName)
@@ -32,58 +15,16 @@ public sealed class DuplicateLookupKeyException : ArgumentException
         DuplicateIndex = duplicateIndex;
     }
 
-    /// <summary>A chave repetida.</summary>
     public string LookupKey { get; }
 
-    /// <summary>Onde ela apareceu pela primeira vez.</summary>
     public int FirstIndex { get; }
 
-    /// <summary>Onde ela reapareceu.</summary>
     public int DuplicateIndex { get; }
 }
 
-/// <summary>
-/// Planejamento de ingestao <b>idempotente por lookup-key</b>: dada uma remessa e o que o
-/// acervo ja tem, diz o que entrou, o que mudou, o que sumiu e o que ficou igual.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Funcao pura, sem I/O.</b> Nao abre conexao, nao chama embedding, nao mede tempo — o
-/// que a torna testavel sem banco e, mais importante, torna a idempotencia <b>demonstravel</b>
-/// em vez de prometida: aplicar o plano e replanejar a mesma entrada tem de devolver
-/// <see cref="DeltaPlan{T}.IsNoOp"/> verdadeiro.
-/// </para>
-/// <para>
-/// <b>A chave e a identidade; o hash e a versao.</b> Sao duas perguntas diferentes e por isso
-/// dois delegados: <c>lookupKey</c> responde "e o mesmo documento?" e <c>contentHash</c>
-/// responde "mudou?". Colapsar as duas num campo so — usar o hash como chave — faz cada
-/// edicao parecer um documento novo e o original parecer removido, que e a ingestao
-/// apaga-tudo com outro nome.
-/// </para>
-/// </remarks>
 public static class DeltaIngest
 {
-    /// <summary>
-    /// Compara a remessa com o acervo e devolve o plano.
-    /// </summary>
-    /// <typeparam name="T">O item ingerido.</typeparam>
-    /// <param name="incoming">A remessa. Enumerada uma unica vez.</param>
-    /// <param name="lookupKey">
-    /// A identidade estavel do item — o que faz duas versoes do mesmo documento serem o
-    /// mesmo documento. Nula ou em branco e recusada: uma chave vazia colapsaria itens
-    /// distintos num so.
-    /// </param>
-    /// <param name="contentHash">
-    /// A versao do conteudo. Igual significa "nao mudou"; diferente significa "mudou". Nulo e
-    /// recusado — sem hash nao ha como distinguir <c>Unchanged</c> de <c>Updated</c>, e
-    /// tratar a ausencia como "mudou" reintroduziria o re-embedding de tudo.
-    /// </param>
-    /// <param name="existingHashes">
-    /// O que o acervo tem hoje: lookup-key para hash de conteudo. As chaves daqui que nao
-    /// aparecerem na remessa saem em <see cref="DeltaPlan{T}.Removed"/>.
-    /// </param>
-    /// <exception cref="DuplicateLookupKeyException">A mesma chave veio duas vezes.</exception>
-    /// <exception cref="ArgumentException">Um item produziu chave ou hash nulo/em branco.</exception>
+    // A chave e a identidade e o hash e a versao: usar o hash como chave faz cada edicao virar remocao + insercao.
     public static DeltaPlan<T> Plan<T>(
         IEnumerable<T> incoming,
         Func<T, string> lookupKey,
@@ -99,9 +40,6 @@ public static class DeltaIngest
         List<T> updated = [];
         List<T> unchanged = [];
 
-        // Comparacao ordinal, explicita: a chave e um identificador, nao texto de usuario.
-        // Deixar a cultura decidir faria o mesmo corpus produzir planos diferentes conforme a
-        // maquina que roda a ingestao.
         var seen = new Dictionary<string, int>(StringComparer.Ordinal);
         var index = 0;
 
@@ -151,9 +89,6 @@ public static class DeltaIngest
             index++;
         }
 
-        // O que o acervo tem e a remessa nao trouxe. Note que 'seen' e consultado pela MESMA
-        // chave e com o MESMO comparador usados acima — uma segunda nocao de igualdade aqui
-        // faria itens presentes serem reportados como removidos.
         List<string> removed = [];
 
         foreach (var key in existingHashes.Keys)

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Rag/DeltaPlan.cs

@@ -1,55 +1,14 @@
 namespace Morph.AiKit.Rag;
 
-/// <summary>
-/// O que precisa acontecer no acervo para que ele passe a refletir a entrada — e nada mais.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>O defeito que este tipo existe para matar</b> e o apaga-e-regrava: a base de
-/// conhecimento do GHLBrain <b>apaga e re-embeda o documento inteiro</b> a cada ingestao,
-/// mudou ou nao. O custo e pago em embedding de trecho que nao mudou e em latencia (uma
-/// chamada de embedding por item no reindex em massa). Um plano em quatro baldes torna
-/// visivel o que a ingestao inteira escondia: quase sempre <see cref="Unchanged"/> e a lista
-/// grande e as outras tres sao curtas.
-/// </para>
-/// <para>
-/// Errata (2026-09-15, Morph.GHLBrain#96): a versao anterior deste comentario citava tambem
-/// uma janela entre o apagar e o gravar em que a busca nao acha nada. No GHLBrain o apagar e
-/// o gravar ja rodam numa transacao so, com o embedding antes dela, entao essa janela nao
-/// existe la. Ela existe em quem apaga fora da transacao que grava.
-/// </para>
-/// <para>
-/// <b>E um plano, nao uma execucao.</b> Nada aqui toca banco, vetor ou arquivo: quem aplica
-/// e o projeto, que sabe qual e a sua transacao. E por isso que a idempotencia da ingestao
-/// pode ser provada sem subir infraestrutura nenhuma.
-/// </para>
-/// </remarks>
-/// <typeparam name="T">O item ingerido — documento, trecho, linha.</typeparam>
-/// <param name="Added">Itens cuja chave nao existia no acervo.</param>
-/// <param name="Updated">Itens cuja chave existia com <b>outro</b> conteudo.</param>
-/// <param name="Removed">
-/// Chaves que estavam no acervo e <b>nao vieram</b> na entrada. Sao chaves, e nao itens:
-/// o que sumiu da origem nao tem corpo para carregar.
-/// </param>
-/// <param name="Unchanged">
-/// Itens cuja chave existia com o <b>mesmo</b> conteudo. Nao re-embedar estes e a economia
-/// inteira desta feature.
-/// </param>
 public sealed record DeltaPlan<T>(
     IReadOnlyList<T> Added,
     IReadOnlyList<T> Updated,
     IReadOnlyList<string> Removed,
     IReadOnlyList<T> Unchanged)
 {
-    /// <summary>Plano vazio — nem entrada, nem acervo.</summary>
     public static DeltaPlan<T> Empty { get; } = new([], [], [], []);
 
-    /// <summary>
-    /// Se o acervo ja reflete a entrada. <b>E a idempotencia expressa como predicado:</b>
-    /// re-planejar a mesma entrada sobre o acervo que ela produziu tem de dar verdadeiro.
-    /// </summary>
     public bool IsNoOp => Added.Count == 0 && Updated.Count == 0 && Removed.Count == 0;
 
-    /// <summary>Quantos itens da entrada tocam o acervo. Zero num plano idempotente.</summary>
     public int WriteCount => Added.Count + Updated.Count + Removed.Count;
 }

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/AgentFactoryTests.cs

@@ -8,23 +8,8 @@ using Xunit;
 
 namespace Morph.AiKit.Tests;
 
-/// <summary>
-/// Canarios da <see cref="AgentFactory"/> (T10). Duas afirmacoes sao o coracao do arquivo:
-/// <b>a precedencia do protocolo</b> (spec vence o alias quando presente, alias vence quando
-/// a spec cala) e <b>a ordem do pipeline</b>, observada na sequencia real de chamadas, nao
-/// na leitura do codigo.
-/// </summary>
-/// <remarks>
-/// Todo <c>await</c> passa <c>TestContext.Current.CancellationToken</c> — exigencia do
-/// analisador xUnit1051, que sob <c>TreatWarningsAsErrors</c> e build vermelho.
-/// </remarks>
 public sealed class AgentFactoryTests
 {
-    // ---------------------------------------------------------------------------------
-    // Documentos de registry usados pelos casos
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>Um alias Responses e um alias Chat COM o limite do GPT-5.4 declarado.</summary>
     private const string TwoProtocolsDocument = """
     {
       "version": "2.0",
@@ -53,14 +38,6 @@ public sealed class AgentFactoryTests
     private static AgentSpec Spec(string alias = "responses-alias", AgentApi? api = null)
         => new() { Alias = alias, Instructions = "voce e um agente de teste", Api = api };
 
-    // ---------------------------------------------------------------------------------
-    // doneCriteria 1 — a precedencia do api:
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// Spec calada: vale o <c>api:</c> do alias. O seletor de cliente e o observatorio —
-    /// ele recebe o protocolo <b>efetivo</b>, ja resolvido.
-    /// </summary>
     [Fact]
     public void TheAliasApiWinsWhenTheSpecDeclaresNone()
     {
@@ -77,11 +54,6 @@ public sealed class AgentFactoryTests
         Assert.Equal([AgentApi.Responses, AgentApi.Chat], seen);
     }
 
-    /// <summary>
-    /// Spec preenchida: ela vence, nos dois sentidos. A regra nao e reimplementada aqui —
-    /// a fabrica chama <see cref="AgentSpec.ResolveApi"/> (T7), e este teste morre se
-    /// alguem inverter a precedencia la ou copia-la para ca.
-    /// </summary>
     [Fact]
     public void TheSpecApiWinsOverTheAliasInBothDirections()
     {
@@ -98,11 +70,6 @@ public sealed class AgentFactoryTests
         Assert.Equal([AgentApi.Chat, AgentApi.Responses], seen);
     }
 
-    /// <summary>
-    /// Sem seletor, "a spec vence" nao pode ser cumprido: o registry memoiza UM cliente por
-    /// alias, construido para o protocolo do alias. A fabrica recusa nomeando os dois
-    /// protocolos, em vez de devolver um agente que diz falar um e fala outro.
-    /// </summary>
     [Fact]
     public void WithoutASelectorADivergentSpecApiIsRefusedNamingBothProtocols()
     {
@@ -118,10 +85,6 @@ public sealed class AgentFactoryTests
         Assert.Contains("responses-alias", error.Message, StringComparison.Ordinal);
     }
 
-    /// <summary>
-    /// Sem divergencia e sem seletor, o caminho normal: o cliente memoizado do alias, uma
-    /// unica construcao por alias, por mais agentes que se criem.
-    /// </summary>
     [Fact]
     public void WithoutASelectorEveryAgentOfAnAliasSharesTheMemoizedClient()
     {
@@ -135,20 +98,6 @@ public sealed class AgentFactoryTests
         Assert.Equal(1, providerFactory.CreateCount);
     }
 
-    // ---------------------------------------------------------------------------------
-    // doneCriteria 2 — a ordem do pipeline, observada nas chamadas
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// A ordem completa, medida numa invocacao com <b>duas</b> voltas de tool calling.
-    /// </summary>
-    /// <remarks>
-    /// O que a sequencia prova, e que nenhuma leitura de codigo prova: o encaixe de custo
-    /// entra e sai <b>uma</b> vez envolvendo as duas voltas (esta ACIMA do
-    /// <c>FunctionInvokingChatClient</c>), e o encaixe de telemetria entra e sai <b>duas</b>
-    /// vezes, uma por chamada ao modelo (esta ABAIXO). Trocar os dois de lugar muda esta
-    /// lista, e o teste morre.
-    /// </remarks>
     [Fact]
     public async Task ThePipelineOrderIsUsageCostAboveFunctionInvocationAndTelemetryBelowIt()
     {
@@ -180,12 +129,7 @@ public sealed class AgentFactoryTests
             log);
     }
 
-    /// <summary>
-    /// A razao de o custo ficar acima do FICC, em numeros: ele ve UMA resposta com o uso
-    /// somado das duas voltas (10+30 de entrada, 4+6 de saida). Abaixo do FICC veria duas
-    /// respostas parciais — e leria um <c>UsageDetails</c> que o proprio FICC muta para
-    /// acumular, o que faria a mesma conta sair diferente conforme a hora de ler.
-    /// </summary>
+    // Abaixo do FunctionInvokingChatClient o custo leria o UsageDetails que ele muta para acumular entre voltas.
     [Fact]
     public async Task UsageCostAboveFunctionInvocationSeesTheUsageOfEveryToolRoundSummedOnce()
     {
@@ -209,15 +153,6 @@ public sealed class AgentFactoryTests
         Assert.Equal(10, usage.OutputTokenCount);
     }
 
-    // ---------------------------------------------------------------------------------
-    // As opcoes de nivel de agente (T7) chegam ao lugar que a T7 declarou
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// <c>MaxToolIterations</c> e <c>AllowConcurrentToolInvocation</c> tem destino nomeado
-    /// no contrato da T7. Aqui eles sao lidos <b>do objeto real</b> do pipeline, via
-    /// <c>GetService</c> — nao de um campo que a fabrica tenha guardado.
-    /// </summary>
     [Fact]
     public void TheAgentLevelKnobsReachTheFunctionInvokingChatClient()
     {
@@ -236,10 +171,6 @@ public sealed class AgentFactoryTests
         Assert.True(functionInvoking.AllowConcurrentInvocation);
     }
 
-    /// <summary>
-    /// <c>TimeoutSeconds</c> vira <see cref="CancellationToken"/> de verdade: um cliente que
-    /// nunca responde e cancelado, em vez de pendurar a invocacao.
-    /// </summary>
     [Fact]
     public async Task TimeoutSecondsBecomesACancellationTokenThatActuallyCancels()
     {
@@ -260,15 +191,6 @@ public sealed class AgentFactoryTests
             () => agent.RunAsync("oi", session, cancellationToken: TestContext.Current.CancellationToken));
     }
 
-    // ---------------------------------------------------------------------------------
-    // A spec inteira chega as ChatOptions do agente
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// O modelo vem do alias (a spec nunca cita modelo), as instrucoes e o schema vem da
-    /// spec, e <see cref="AgentSpecOptions.ApplyTo"/> nao atropela nem as tools nem o
-    /// formato de resposta ja definidos.
-    /// </summary>
     [Fact]
     public async Task TheSpecReachesTheChatOptionsWithoutClobberingToolsOrSchema()
     {
@@ -304,14 +226,6 @@ public sealed class AgentFactoryTests
         Assert.Equal("agente-de-teste", agent.Name);
     }
 
-    // ---------------------------------------------------------------------------------
-    // Recusas
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// Limite de alias violado nao vira agente. A recusa carrega a procedencia escrita no
-    /// registry — sem ela, o limite nao teria sequer carregado (T8).
-    /// </summary>
     [Fact]
     public void AViolatedAliasConstraintRefusesTheAgentAndCarriesItsProvenance()
     {
@@ -328,11 +242,6 @@ public sealed class AgentFactoryTests
         Assert.Contains("issue #93", error.Message, StringComparison.Ordinal);
     }
 
-    /// <summary>
-    /// O MESMO alias, sem tools, nao viola nada: o limite tem quatro fatos, e tres nao
-    /// bastam. O canario existe para que a recusa acima nao seja confundida com "modelo de
-    /// raciocinio rejeita tool".
-    /// </summary>
     [Fact]
     public void TheSameAliasWithoutToolsCreatesTheAgentNormally()
     {
@@ -347,7 +256,6 @@ public sealed class AgentFactoryTests
         Assert.NotNull(agent);
     }
 
-    /// <summary>Alias desconhecido falha na fabrica com o mesmo erro do registry.</summary>
     [Fact]
     public void AnUnknownAliasFailsAtCreateTime()
     {
@@ -359,7 +267,6 @@ public sealed class AgentFactoryTests
         Assert.Equal(ModelRegistryError.UnknownAlias, error.Reason);
     }
 
-    /// <summary>Seletor que devolve nulo e recusa explicita, nunca agente sem cliente.</summary>
     [Fact]
     public void ASelectorThatReturnsNullIsRefusedInsteadOfProducingAClientlessAgent()
     {
@@ -374,10 +281,6 @@ public sealed class AgentFactoryTests
         Assert.Equal(AgentFactoryError.NoChatClient, error.Reason);
     }
 
-    /// <summary>
-    /// Sem nenhum encaixe preenchido, o agente e valido e responde. Um agente sem custo e
-    /// sem telemetria nao e um agente pela metade.
-    /// </summary>
     [Fact]
     public async Task AnAgentWithNoHooksIsStillAValidAgentThatAnswers()
     {
@@ -395,15 +298,7 @@ public sealed class AgentFactoryTests
         Assert.Equal("pronto", response.Text);
     }
 
-    // ---------------------------------------------------------------------------------
-    // Apoio dos testes
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// Roteiro de duas voltas: o modelo pede a tool, a tool responde, o modelo conclui. Os
-    /// numeros de uso sao escolhidos para que a soma (40/10) seja distinguivel de qualquer
-    /// uma das parcelas.
-    /// </summary>
+    // Os usos por volta (10/4 e 30/6) diferem da soma (40/10), para a soma nao se confundir com uma parcela.
     private static FakeChatClient ScriptedToolCallThenAnswer()
         => new FakeChatClient()
             .Enqueue(new ChatResponse(new ChatMessage(
@@ -433,10 +328,6 @@ public sealed class AgentFactoryTests
         return factory.Create(spec);
     }
 
-    /// <summary>
-    /// Marca a entrada e a saida de uma posicao do pipeline. E o unico jeito de observar a
-    /// ORDEM: ela nao esta em nenhuma propriedade, so na sequencia das chamadas.
-    /// </summary>
     private sealed class ProbeChatClient(
         IChatClient inner,
         string tag,
@@ -465,7 +356,6 @@ public sealed class AgentFactoryTests
         }
     }
 
-    /// <summary>Cliente que nunca responde — existe so para o timeout ter o que cancelar.</summary>
     private sealed class NeverAnsweringChatClient : IChatClient
     {
         public async Task<ChatResponse> GetResponseAsync(

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/AgentSpecTests.cs

@@ -7,24 +7,8 @@ using Xunit;
 
 namespace Morph.AiKit.Tests;
 
-/// <summary>
-/// Canarios do agente-como-dado (T7). O que estes testes protegem nao e a existencia dos
-/// tipos — o compilador ja faz isso — e sim a UNICA regra estrutural que
-/// <see cref="AgentSpecOptions"/> tem: <b>nulo nao envia nada ao provider</b>.
-/// </summary>
-/// <remarks>
-/// A comparacao e feita por reflexao contra um <see cref="ChatOptions"/> virgem, e nao
-/// contra uma lista de propriedades escrita a mao, de proposito: uma propriedade nova no
-/// <c>Microsoft.Extensions.AI</c> entra na comparacao sozinha. Uma lista escrita a mao
-/// envelheceria em silencio no proximo bump do pin — que e exatamente o defeito que a
-/// feature inteira existe para matar.
-/// </remarks>
 public sealed class AgentSpecTests
 {
-    // ---------------------------------------------------------------------------------
-    // A regra estrutural: nulo = nao envia
-    // ---------------------------------------------------------------------------------
-
     [Fact]
     public void FreshOptionsProduceChatOptionsIndistinguishableFromPristine()
     {
@@ -68,9 +52,7 @@ public sealed class AgentSpecTests
     [Fact]
     public void AgentLevelKnobsNeverLeakIntoChatOptions()
     {
-        // As quatro opcoes de nivel de agente. Nenhuma tem casa em ChatOptions: elas sao
-        // lidas pela AgentFactory (T10) e pela telemetria (T12). Se alguem "resolver" isso
-        // despejando-as em AdditionalProperties, este teste morre — que e o ponto.
+        // As quatro opcoes de nivel de agente nao tem casa em ChatOptions: a AgentFactory e a telemetria as leem.
         var produced = new AgentSpecOptions
         {
             MaxToolIterations = 7,
@@ -86,10 +68,6 @@ public sealed class AgentSpecTests
             $"Opcao de nivel de agente vazou para ChatOptions: {string.Join(", ", differing)}");
     }
 
-    // ---------------------------------------------------------------------------------
-    // Mapeamento de cada opcao de nivel de requisicao para a sua casa
-    // ---------------------------------------------------------------------------------
-
     [Fact]
     public void EachRequestLevelOptionLandsInItsOwnChatOptionsHome()
     {
@@ -115,8 +93,7 @@ public sealed class AgentSpecTests
         Assert.Same(ChatToolMode.RequireAny, produced.ToolMode);
         Assert.Equal(ReasoningEffort.Medium, produced.Reasoning?.Effort);
 
-        // service tier NAO existe em ChatOptions no Microsoft.Extensions.AI 10.9.0 (apurado
-        // por reflexao sobre o assembly do pin) — viaja em AdditionalProperties.
+        // ServiceTier nao existe em ChatOptions no Microsoft.Extensions.AI 10.9.0: viaja em AdditionalProperties.
         Assert.NotNull(produced.AdditionalProperties);
         Assert.True(produced.AdditionalProperties.TryGetValue(
             AgentSpecOptions.ServiceTierPropertyName,
@@ -127,8 +104,6 @@ public sealed class AgentSpecTests
     [Fact]
     public void AnExplicitlyEmptyStopSequenceListIsSentAsWritten()
     {
-        // "Nulo nao envia; nao-nulo envia o que voce escreveu." Tratar lista vazia como
-        // nula seria uma excecao escondida na unica regra do tipo.
         var produced = new AgentSpecOptions { StopSequences = [] }.ToChatOptions();
 
         Assert.Equal([nameof(ChatOptions.StopSequences)], DiffAgainstPristine(produced));
@@ -139,7 +114,6 @@ public sealed class AgentSpecTests
     [Fact]
     public void ApplyToNeverClobbersWhatTheCallerAlreadySet()
     {
-        // A AgentFactory (T10) preenche Tools e ResponseFormat; ApplyTo nao pode apaga-los.
         var destination = new ChatOptions
         {
             ResponseFormat = ChatResponseFormat.Json,
@@ -158,10 +132,6 @@ public sealed class AgentSpecTests
     public void ApplyToRejectsANullDestination()
         => Assert.Throws<ArgumentNullException>(() => new AgentSpecOptions().ApplyTo(null!));
 
-    // ---------------------------------------------------------------------------------
-    // AgentSpec
-    // ---------------------------------------------------------------------------------
-
     [Fact]
     public void AFreshSpecCarriesNoToolsNoSchemaAndSendsNoOptions()
     {
@@ -194,11 +164,9 @@ public sealed class AgentSpecTests
         var withoutOverride = new AgentSpec { Alias = "a", Instructions = "i" };
         var withOverride = withoutOverride with { Api = AgentApi.Chat };
 
-        // alias manda quando a spec nao opinou
         Assert.Equal(AgentApi.Responses, withoutOverride.ResolveApi(AgentApi.Responses));
         Assert.Equal(AgentApi.Chat, withoutOverride.ResolveApi(AgentApi.Chat));
 
-        // spec manda quando opinou — inclusive contra o alias
         Assert.Equal(AgentApi.Chat, withOverride.ResolveApi(AgentApi.Responses));
     }
 
@@ -222,15 +190,6 @@ public sealed class AgentSpecTests
         Assert.Equal("object", spec.OutputSchema.Value.GetProperty("type").GetString());
     }
 
-    // ---------------------------------------------------------------------------------
-    // Helpers
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// Nomes das propriedades de <see cref="ChatOptions"/> em que <paramref name="actual"/>
-    /// difere de um <see cref="ChatOptions"/> virgem — ou seja, o conjunto exato do que
-    /// seria enviado ao provider.
-    /// </summary>
     private static IReadOnlyList<string> DiffAgainstPristine(ChatOptions actual)
     {
         var pristine = new ChatOptions();