@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

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

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

@@ -7,21 +7,6 @@ using Xunit;
 
 namespace Morph.AiKit.Tests;
 
-/// <summary>
-/// Canarios do <see cref="ConversationStore"/> (T13). A afirmacao central: <b>uma unica
-/// instancia de provider atende todas as sessoes, e o historico de uma conversa nunca
-/// aparece em outra</b> — porque o estado por sessao vive na
-/// <see cref="AgentSession"/> (via <see cref="ProviderSessionState{TState}"/>), jamais num
-/// campo do provider.
-/// </summary>
-/// <remarks>
-/// Os testes rodam pelo caminho <b>real</b> do MAF: um <see cref="ChatClientAgent"/> de
-/// verdade, com <c>ChatClientAgentOptions.ChatHistoryProvider</c> apontando para o
-/// <see cref="ConversationStore"/>, sessoes criadas por <c>CreateSessionAsync</c> e voltas
-/// disparadas por <c>RunAsync</c>. O unico fake e o <see cref="FakeChatClient"/> no lugar do
-/// provider de modelo — e por isso "o provider e chamado" e um fato observado, e nao uma
-/// chamada manual ao metodo protegido fingindo ser o framework.
-/// </remarks>
 public sealed class ConversationStoreTests
 {
     private static ChatClientAgent Agent(FakeChatClient client, ConversationStore history)
@@ -37,15 +22,6 @@ public sealed class ConversationStoreTests
     private static string[] TextsOf(IEnumerable<ChatMessage> messages)
         => [.. messages.Select(m => m.Text)];
 
-    // ---------------------------------------------------------------------------------
-    // doneCriteria 2: AppendAsync recebe a volta; LoadAsync alimenta a volta seguinte
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// Uma volta e gravada com pedido e resposta, nessa ordem — e a volta seguinte chega ao
-    /// modelo ja com essa historia na frente. As duas metades do contrato, medidas nos dois
-    /// lados: no acervo e no que o cliente de modelo recebeu.
-    /// </summary>
     [Fact]
     public async Task TheRoundIsAppendedAndFeedsTheHistoryOfTheNextRound()
     {
@@ -61,7 +37,6 @@ public sealed class ConversationStoreTests
 
         await agent.RunAsync("Meu pedido 1234 esta atrasado.", session, cancellationToken: Ct);
 
-        // Depois da 1a volta o acervo tem exatamente o pedido e a resposta daquela volta.
         var afterFirst = await store.LoadAsync("conversa-A", Ct);
         Assert.Equal(
             ["Meu pedido 1234 esta atrasado.", "Vou verificar o pedido 1234."],
@@ -69,8 +44,6 @@ public sealed class ConversationStoreTests
 
         await agent.RunAsync("E quando foi despachado?", session, cancellationToken: Ct);
 
-        // A 2a ida ao modelo levou o historico carregado do acervo, e so uma vez cada
-        // mensagem — o turno corrente nao vem duplicado.
         var secondCall = TextsOf(client.ReceivedMessages[1]);
         Assert.Equal(
             [
@@ -84,10 +57,6 @@ public sealed class ConversationStoreTests
         Assert.Equal(4, afterSecond.Count);
     }
 
-    /// <summary>
-    /// A primeira volta nao carrega historico nenhum: conversa inexistente e lista vazia, nao
-    /// erro. E o caso mais comum de todos.
-    /// </summary>
     [Fact]
     public async Task AConversationThatDoesNotExistYetLoadsEmptyInsteadOfFailing()
     {
@@ -106,19 +75,6 @@ public sealed class ConversationStoreTests
         Assert.Equal(["oi", "ola"], TextsOf(await store.LoadAsync("conversa-nova", Ct)));
     }
 
-    // ---------------------------------------------------------------------------------
-    // doneCriteria 1: DUAS sessoes concorrentes na MESMA instancia, sem vazamento
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// <b>O canario da invariante.</b> Uma instancia de <see cref="ConversationStore"/>, duas
-    /// sessoes, muitas voltas intercaladas em paralelo: nenhuma mensagem de uma conversa
-    /// aparece na outra, e cada uma tem exatamente as suas.
-    /// </summary>
-    /// <remarks>
-    /// Este e o teste que morre se alguem guardar "a conversa atual" num campo do provider —
-    /// o defeito que em producao aparece como historico de um usuario na tela de outro.
-    /// </remarks>
     [Fact]
     public async Task TwoConcurrentSessionsOnTheSameProviderNeverSeeEachOthersMessages()
     {
@@ -136,7 +92,6 @@ public sealed class ConversationStoreTests
             clientB.EnqueueText($"resposta-B-{i}");
         }
 
-        // Duas conversas distintas, o MESMO provider de historico nos dois agentes.
         var agentA = Agent(clientA, history);
         var agentB = Agent(clientB, history);
 
@@ -145,7 +100,7 @@ public sealed class ConversationStoreTests
         history.BindConversation(sessionA, "conversa-A");
         history.BindConversation(sessionB, "conversa-B");
 
-        // Sequencial DENTRO de cada sessao (uma conversa e uma fila), concorrente ENTRE elas.
+        // Sequencial dentro de cada sessao (uma conversa e uma fila), concorrente entre elas.
         var driveA = Task.Run(async () =>
         {
             for (var i = 0; i < Rounds; i++)
@@ -170,26 +125,18 @@ public sealed class ConversationStoreTests
         Assert.Equal(Rounds * 2, conversationA.Length);
         Assert.Equal(Rounds * 2, conversationB.Length);
 
-        // Nenhum texto do outro lado atravessou.
         Assert.DoesNotContain(conversationA, t => t.Contains("-B-", StringComparison.Ordinal));
         Assert.DoesNotContain(conversationB, t => t.Contains("-A-", StringComparison.Ordinal));
 
-        // E cada conversa tem as suas, na ordem.
         Assert.Equal(
             [.. Enumerable.Range(0, Rounds).SelectMany(i => new[] { $"pergunta-A-{i}", $"resposta-A-{i}" })],
             conversationA);
 
-        // O que o modelo VIU tambem nao se misturou: a ultima ida de A nao carrega nada de B.
         Assert.DoesNotContain(
             TextsOf(clientA.ReceivedMessages[^1]),
             t => t.Contains("-B-", StringComparison.Ordinal));
     }
 
-    /// <summary>
-    /// A prova direta de que o estado por sessao <b>mora na sessao</b>: o mesmo provider
-    /// devolve ids diferentes para sessoes diferentes, e o id de cada sessao esta gravado
-    /// no <c>StateBag</c> dela — que e onde o MAF o serializa e o retoma.
-    /// </summary>
     [Fact]
     public async Task TheConversationIdLivesInTheSessionStateNotInAProviderField()
     {
@@ -204,19 +151,13 @@ public sealed class ConversationStoreTests
         var secondId = history.GetConversationId(second);
 
         Assert.NotEqual(firstId, secondId);
-        Assert.Equal(firstId, history.GetConversationId(first));   // estavel na mesma sessao
+        Assert.Equal(firstId, history.GetConversationId(first));
 
-        // Esta gravado na sessao, sob a chave que o provider declara em StateKeys.
         Assert.True(first.StateBag.TryGetValue<string>(ConversationStore.ConversationIdStateKey, out var stored));
         Assert.Equal(firstId, stored);
         Assert.Contains(ConversationStore.ConversationIdStateKey, history.StateKeys);
     }
 
-    /// <summary>
-    /// Sem amarracao explicita o id e um <see cref="Guid.CreateVersion7"/> — ordenavel no
-    /// tempo, ao contrario de <c>Guid.NewGuid</c>. A versao 7 e legivel no proprio valor
-    /// (o nibble de versao), entao a regra da casa e verificavel e nao so declarada.
-    /// </summary>
     [Fact]
     public async Task AnUnboundSessionGetsATimeOrderedIdentifier()
     {
@@ -231,11 +172,6 @@ public sealed class ConversationStoreTests
         Assert.Equal(7, parsed.ToByteArray(bigEndian: true)[6] >> 4);
     }
 
-    /// <summary>
-    /// O caminho do CRM: a conversa ja existe como registro, e a sessao entra nela — o
-    /// historico anterior aparece na primeira volta desta sessao. E o que torna a decisao
-    /// "conversa no acervo do projeto" util em vez de teorica.
-    /// </summary>
     [Fact]
     public async Task ASessionCanJoinAConversationThatAlreadyExistsInTheProjectStore()
     {
@@ -258,21 +194,10 @@ public sealed class ConversationStoreTests
         await agent.RunAsync("Nao chegou.", session, cancellationToken: Ct);
 
         Assert.Contains("Ontem eu pedi um orcamento.", TextsOf(client.ReceivedMessages[0]));
-        // 2 do acervo anterior + o pedido e a resposta desta volta. A volta grava SO a si
-        // mesma: regravar o historico inteiro faria a conversa crescer em progressao
-        // geometrica a cada turno.
+        // 2 do acervo + pedido e resposta desta volta: a volta grava so a si mesma.
         Assert.Equal(4, (await store.LoadAsync("crm-conversa-42", Ct)).Count);
     }
 
-    // ---------------------------------------------------------------------------------
-    // O acervo e plugavel: o kit nao conhece banco
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// A costura e substituivel: um acervo de teste que apenas anota as chamadas prova que o
-    /// provider fala com <see cref="IConversationStore"/> e com mais nada — e um projeto que
-    /// troque memoria por <c>jsonb</c> so implementa esta interface.
-    /// </summary>
     [Fact]
     public async Task TheProviderTalksOnlyToTheSeamSoPersistenceIsReplaceable()
     {
@@ -289,11 +214,6 @@ public sealed class ConversationStoreTests
         Assert.Equal(["load:c-1", "append:c-1"], spy.Calls);
     }
 
-    /// <summary>
-    /// Volta que falhou nao vira historico. Persistir o pedido sem resposta deixaria a
-    /// conversa terminando numa pergunta nunca respondida — e a volta seguinte a repetiria,
-    /// com o usuario se vendo duplicado.
-    /// </summary>
     [Fact]
     public async Task AFailedRoundIsNotPersisted()
     {
@@ -311,22 +231,7 @@ public sealed class ConversationStoreTests
         Assert.Empty(await store.LoadAsync("conversa-falha", Ct));
     }
 
-    /// <summary>
-    /// <b>Uma volta sem sessao.</b> O MAF declara <c>InvokingContext.Session</c> como
-    /// anulavel, e o provider recusa esse caso: inventar um id gravaria conversa orfa e usar
-    /// uma chave fixa juntaria tenants no mesmo balde — as duas saidas silenciosas sao
-    /// piores que a recusa. Este teste mede o que o framework realmente faz por esse
-    /// caminho, em vez de supor: e o comportamento observado que fica pinado aqui.
-    /// </summary>
-    /// <remarks>
-    /// O caminho de construir <c>InvokingContext</c> a mao — que seria a forma direta de
-    /// exercitar a guarda — <b>nao esta disponivel</b>: no MAF 1.20.0 os construtores de
-    /// <c>InvokingContext</c> e <c>InvokedContext</c> sao os unicos membros da area de
-    /// <c>ChatHistoryProvider</c> marcados <c>[Experimental("MAAI001")]</c>, e com
-    /// <c>TreatWarningsAsErrors</c> isso e erro de compilacao. Consequencia registrada: um
-    /// provider de historico so pode ser testado <b>atraves de um agente real</b>, que e
-    /// como esta classe inteira o testa.
-    /// </remarks>
+    // No MAF 1.20.0 o construtor de InvokingContext e [Experimental("MAAI001")]: o provider so se exercita via agente real.
     [Fact]
     public async Task ARoundWithoutAnExplicitSessionStillHasAConversationOfItsOwn()
     {
@@ -337,14 +242,10 @@ public sealed class ConversationStoreTests
 
         await agent.RunAsync("sem sessao", cancellationToken: Ct);
 
-        // O agente cria uma sessao efemera para a volta: a guarda de sessao ausente nao e
-        // alcancada por este caminho, e a conversa nasce com id proprio em vez de cair num
-        // balde compartilhado.
+        // Sem sessao, o agente cria uma efemera para a volta: a conversa nasce com id proprio.
         var conversation = Assert.Single(store.ConversationIds);
         Assert.Equal(["sem sessao", "respondido"], TextsOf(await store.LoadAsync(conversation, Ct)));
 
-        // E a volta seguinte, tambem sem sessao, NAO herda a conversa anterior — sem sessao
-        // nao ha continuidade, que e a semantica correta de uma chamada avulsa.
         client.EnqueueText("de novo");
         await agent.RunAsync("outra avulsa", cancellationToken: Ct);
 
@@ -352,15 +253,10 @@ public sealed class ConversationStoreTests
         Assert.DoesNotContain("sem sessao", TextsOf(client.ReceivedMessages[^1]));
     }
 
-    /// <summary>Provider sem acervo e defeito de composicao, e falha na construcao.</summary>
     [Fact]
     public void TheProviderRefusesToBeBuiltWithoutAStore()
         => Assert.Throws<ArgumentNullException>(() => new ConversationStore(null!));
 
-    /// <summary>
-    /// O acervo em memoria e ele proprio seguro sob concorrencia — senao o canario das duas
-    /// sessoes mediria a falta de trava aqui, e nao o isolamento do provider.
-    /// </summary>
     [Fact]
     public async Task TheInMemoryStoreDoesNotLoseWritesUnderConcurrency()
     {
@@ -378,7 +274,6 @@ public sealed class ConversationStoreTests
         Assert.Empty(await store.LoadAsync("inexistente", Ct));
     }
 
-    /// <summary>Acervo de teste que so anota o que lhe pediram, na ordem.</summary>
     private sealed class RecordingConversationStore : IConversationStore
     {
         private readonly ConcurrentQueue<string> _calls = new();