@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,260 @@
+using System.Collections;
+using System.Reflection;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+using Morph.AiKit.Agents;
+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()
+    {
+        var produced = new AgentSpecOptions().ToChatOptions();
+
+        var differing = DiffAgainstPristine(produced);
+
+        Assert.True(
+            differing.Count == 0,
+            $"AgentSpecOptions recem-construida NAO pode enviar opcao nenhuma. Enviou: {string.Join(", ", differing)}");
+    }
+
+    [Fact]
+    public void EveryAgentSpecOptionsPropertyIsNullOnAFreshInstance()
+    {
+        var fresh = new AgentSpecOptions();
+
+        var nonNull = typeof(AgentSpecOptions)
+            .GetProperties(BindingFlags.Public | BindingFlags.Instance)
+            .Where(p => p.GetIndexParameters().Length == 0)
+            .Where(p => p.GetValue(fresh) is not null)
+            .Select(p => p.Name)
+            .ToList();
+
+        Assert.True(
+            nonNull.Count == 0,
+            $"Toda propriedade de AgentSpecOptions nasce nula. Nasceram preenchidas: {string.Join(", ", nonNull)}");
+    }
+
+    [Fact]
+    public void SettingOnlyTemperatureSendsOnlyTemperature()
+    {
+        var produced = new AgentSpecOptions { Temperature = 0.2f }.ToChatOptions();
+
+        var differing = DiffAgainstPristine(produced);
+
+        Assert.Equal(new[] { nameof(ChatOptions.Temperature) }, differing);
+        Assert.Equal(0.2f, produced.Temperature);
+    }
+
+    [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.
+        var produced = new AgentSpecOptions
+        {
+            MaxToolIterations = 7,
+            AllowConcurrentToolInvocation = true,
+            TimeoutSeconds = 30,
+            EnableSensitiveTelemetry = true,
+        }.ToChatOptions();
+
+        var differing = DiffAgainstPristine(produced);
+
+        Assert.True(
+            differing.Count == 0,
+            $"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()
+    {
+        var options = new AgentSpecOptions
+        {
+            Temperature = 0.35f,
+            TopP = 0.9f,
+            MaxOutputTokens = 512,
+            Seed = 1234,
+            StopSequences = ["<END>"],
+            ToolMode = ChatToolMode.RequireAny,
+            ReasoningEffort = ReasoningEffort.Medium,
+            ServiceTier = "flex",
+        };
+
+        var produced = options.ToChatOptions();
+
+        Assert.Equal(0.35f, produced.Temperature);
+        Assert.Equal(0.9f, produced.TopP);
+        Assert.Equal(512, produced.MaxOutputTokens);
+        Assert.Equal(1234L, produced.Seed);
+        Assert.Equal(["<END>"], produced.StopSequences);
+        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.
+        Assert.NotNull(produced.AdditionalProperties);
+        Assert.True(produced.AdditionalProperties.TryGetValue(
+            AgentSpecOptions.ServiceTierPropertyName,
+            out var serviceTier));
+        Assert.Equal("flex", serviceTier);
+    }
+
+    [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));
+        Assert.NotNull(produced.StopSequences);
+        Assert.Empty(produced.StopSequences);
+    }
+
+    [Fact]
+    public void ApplyToNeverClobbersWhatTheCallerAlreadySet()
+    {
+        // A AgentFactory (T10) preenche Tools e ResponseFormat; ApplyTo nao pode apaga-los.
+        var destination = new ChatOptions
+        {
+            ResponseFormat = ChatResponseFormat.Json,
+            ModelId = "already-chosen",
+        };
+
+        var returned = new AgentSpecOptions { Temperature = 0.1f }.ApplyTo(destination);
+
+        Assert.Same(destination, returned);
+        Assert.Same(ChatResponseFormat.Json, destination.ResponseFormat);
+        Assert.Equal("already-chosen", destination.ModelId);
+        Assert.Equal(0.1f, destination.Temperature);
+    }
+
+    [Fact]
+    public void ApplyToRejectsANullDestination()
+        => Assert.Throws<ArgumentNullException>(() => new AgentSpecOptions().ApplyTo(null!));
+
+    // ---------------------------------------------------------------------------------
+    // AgentSpec
+    // ---------------------------------------------------------------------------------
+
+    [Fact]
+    public void AFreshSpecCarriesNoToolsNoSchemaAndSendsNoOptions()
+    {
+        var spec = new AgentSpec { Alias = "text-default", Instructions = "Seja util." };
+
+        Assert.Empty(spec.Tools);
+        Assert.Null(spec.OutputSchema);
+        Assert.Null(spec.Api);
+        Assert.NotNull(spec.Options);
+        Assert.Empty(DiffAgainstPristine(spec.Options.ToChatOptions()));
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData("   ")]
+    public void ABlankAliasIsRejectedAtConstruction(string blank)
+        => Assert.Throws<ArgumentException>(
+            () => new AgentSpec { Alias = blank, Instructions = "Seja util." });
+
+    [Theory]
+    [InlineData("")]
+    [InlineData("   ")]
+    public void BlankInstructionsAreRejectedAtConstruction(string blank)
+        => Assert.Throws<ArgumentException>(
+            () => new AgentSpec { Alias = "text-default", Instructions = blank });
+
+    [Fact]
+    public void TheSpecApiWinsWhenPresentAndTheAliasWinsWhenItIsNull()
+    {
+        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));
+    }
+
+    [Fact]
+    public void ResponsesIsTheDefaultOfTheEnumBecauseItIsTheHouseDefault()
+        => Assert.Equal(AgentApi.Responses, default(AgentApi));
+
+    [Fact]
+    public void AnOutputSchemaSurvivesAsLongAsItsDocumentDoes()
+    {
+        using var document = JsonDocument.Parse("""{"type":"object"}""");
+
+        var spec = new AgentSpec
+        {
+            Alias = "text-default",
+            Instructions = "Responda em JSON.",
+            OutputSchema = document.RootElement.Clone(),
+        };
+
+        Assert.Equal(JsonValueKind.Object, spec.OutputSchema!.Value.ValueKind);
+        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();
+
+        return [.. typeof(ChatOptions)
+            .GetProperties(BindingFlags.Public | BindingFlags.Instance)
+            .Where(p => p.GetIndexParameters().Length == 0 && p.CanRead)
+            .Where(p => !ValuesEqual(p.GetValue(actual), p.GetValue(pristine)))
+            .Select(p => p.Name)
+            .OrderBy(name => name, StringComparer.Ordinal)];
+    }
+
+    private static bool ValuesEqual(object? left, object? right)
+    {
+        if (left is null || right is null)
+        {
+            return left is null && right is null;
+        }
+
+        if (left is IEnumerable leftItems and not string && right is IEnumerable rightItems and not string)
+        {
+            return leftItems.Cast<object?>().SequenceEqual(rightItems.Cast<object?>());
+        }
+
+        return Equals(left, right);
+    }
+}

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

@@ -0,0 +1,405 @@
+using System.Collections.Concurrent;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Morph.AiKit.Conversation;
+using Morph.AiKit.Tests.Fakes;
+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)
+        => new(client, new ChatClientAgentOptions
+        {
+            Name = "atendente",
+            ChatOptions = new ChatOptions { Instructions = "Voce e um atendente." },
+            ChatHistoryProvider = history,
+        });
+
+    private static CancellationToken Ct => TestContext.Current.CancellationToken;
+
+    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()
+    {
+        var store = new InMemoryConversationStore();
+        var history = new ConversationStore(store);
+        using var client = new FakeChatClient()
+            .EnqueueText("Vou verificar o pedido 1234.")
+            .EnqueueText("Foi despachado ontem.");
+
+        var agent = Agent(client, history);
+        var session = await agent.CreateSessionAsync(Ct);
+        history.BindConversation(session, "conversa-A");
+
+        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."],
+            TextsOf(afterFirst));
+
+        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(
+            [
+                "Meu pedido 1234 esta atrasado.",
+                "Vou verificar o pedido 1234.",
+                "E quando foi despachado?",
+            ],
+            [.. secondCall.Where(t => t.Length > 0 && t != "Voce e um atendente.")]);
+
+        var afterSecond = await store.LoadAsync("conversa-A", Ct);
+        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()
+    {
+        var store = new InMemoryConversationStore();
+        var history = new ConversationStore(store);
+        using var client = new FakeChatClient().EnqueueText("ola");
+
+        var agent = Agent(client, history);
+        var session = await agent.CreateSessionAsync(Ct);
+        history.BindConversation(session, "conversa-nova");
+
+        Assert.Empty(await store.LoadAsync("conversa-nova", Ct));
+
+        await agent.RunAsync("oi", session, cancellationToken: Ct);
+
+        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()
+    {
+        const int Rounds = 25;
+
+        var store = new InMemoryConversationStore();
+        var history = new ConversationStore(store);
+
+        using var clientA = new FakeChatClient();
+        using var clientB = new FakeChatClient();
+
+        for (var i = 0; i < Rounds; i++)
+        {
+            clientA.EnqueueText($"resposta-A-{i}");
+            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);
+
+        var sessionA = await agentA.CreateSessionAsync(Ct);
+        var sessionB = await agentB.CreateSessionAsync(Ct);
+        history.BindConversation(sessionA, "conversa-A");
+        history.BindConversation(sessionB, "conversa-B");
+
+        // 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++)
+            {
+                await agentA.RunAsync($"pergunta-A-{i}", sessionA, cancellationToken: Ct);
+            }
+        }, Ct);
+
+        var driveB = Task.Run(async () =>
+        {
+            for (var i = 0; i < Rounds; i++)
+            {
+                await agentB.RunAsync($"pergunta-B-{i}", sessionB, cancellationToken: Ct);
+            }
+        }, Ct);
+
+        await Task.WhenAll(driveA, driveB);
+
+        var conversationA = TextsOf(await store.LoadAsync("conversa-A", Ct));
+        var conversationB = TextsOf(await store.LoadAsync("conversa-B", Ct));
+
+        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()
+    {
+        var history = new ConversationStore(new InMemoryConversationStore());
+        using var client = new FakeChatClient();
+        var agent = Agent(client, history);
+
+        var first = await agent.CreateSessionAsync(Ct);
+        var second = await agent.CreateSessionAsync(Ct);
+
+        var firstId = history.GetConversationId(first);
+        var secondId = history.GetConversationId(second);
+
+        Assert.NotEqual(firstId, secondId);
+        Assert.Equal(firstId, history.GetConversationId(first));   // estavel na mesma sessao
+
+        // 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()
+    {
+        var history = new ConversationStore(new InMemoryConversationStore());
+        using var client = new FakeChatClient();
+        var agent = Agent(client, history);
+
+        var session = await agent.CreateSessionAsync(Ct);
+        var id = history.GetConversationId(session);
+
+        Assert.True(Guid.TryParseExact(id, "N", out var parsed));
+        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()
+    {
+        var store = new InMemoryConversationStore();
+        await store.AppendAsync(
+            "crm-conversa-42",
+            [
+                new ChatMessage(ChatRole.User, "Ontem eu pedi um orcamento."),
+                new ChatMessage(ChatRole.Assistant, "Enviei por email."),
+            ],
+            Ct);
+
+        var history = new ConversationStore(store);
+        using var client = new FakeChatClient().EnqueueText("Reenviei agora.");
+        var agent = Agent(client, history);
+
+        var session = await agent.CreateSessionAsync(Ct);
+        history.BindConversation(session, "crm-conversa-42");
+
+        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.
+        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()
+    {
+        var spy = new RecordingConversationStore();
+        var history = new ConversationStore(spy);
+        using var client = new FakeChatClient().EnqueueText("pronto");
+
+        var agent = Agent(client, history);
+        var session = await agent.CreateSessionAsync(Ct);
+        history.BindConversation(session, "c-1");
+
+        await agent.RunAsync("faz", session, cancellationToken: Ct);
+
+        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()
+    {
+        var store = new InMemoryConversationStore();
+        var history = new ConversationStore(store);
+        using var client = new FakeChatClient();   // fila vazia: a volta estoura
+        var agent = Agent(client, history);
+
+        var session = await agent.CreateSessionAsync(Ct);
+        history.BindConversation(session, "conversa-falha");
+
+        await Assert.ThrowsAsync<InvalidOperationException>(
+            () => agent.RunAsync("oi", session, cancellationToken: Ct));
+
+        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>
+    [Fact]
+    public async Task ARoundWithoutAnExplicitSessionStillHasAConversationOfItsOwn()
+    {
+        var store = new InMemoryConversationStore();
+        var history = new ConversationStore(store);
+        using var client = new FakeChatClient().EnqueueText("respondido");
+        var agent = Agent(client, history);
+
+        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.
+        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);
+
+        Assert.Equal(2, store.ConversationIds.Count);
+        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()
+    {
+        var store = new InMemoryConversationStore();
+
+        await Task.WhenAll(Enumerable.Range(0, 100).Select(i => Task.Run(
+            async () => await store.AppendAsync(
+                i % 2 == 0 ? "par" : "impar",
+                [new ChatMessage(ChatRole.User, $"m{i}")],
+                Ct),
+            Ct)));
+
+        Assert.Equal(50, (await store.LoadAsync("par", Ct)).Count);
+        Assert.Equal(50, (await store.LoadAsync("impar", Ct)).Count);
+        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();
+
+        public IReadOnlyList<string> Calls => [.. _calls];
+
+        public ValueTask<IReadOnlyList<ChatMessage>> LoadAsync(
+            string conversationId,
+            CancellationToken cancellationToken)
+        {
+            _calls.Enqueue($"load:{conversationId}");
+            return ValueTask.FromResult<IReadOnlyList<ChatMessage>>([]);
+        }
+
+        public ValueTask AppendAsync(
+            string conversationId,
+            IReadOnlyList<ChatMessage> messages,
+            CancellationToken cancellationToken)
+        {
+            _calls.Enqueue($"append:{conversationId}");
+            return ValueTask.CompletedTask;
+        }
+    }
+}