@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

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

@@ -0,0 +1,139 @@
+using Morph.AiKit.Evals;
+using Morph.AiKit.Tests.Fakes;
+using Xunit;
+
+namespace Morph.AiKit.Tests.Evals;
+
+/// <summary>
+/// Miss de cache sem credencial REPROVA, nomeado. Jamais <c>skip</c>.
+/// </summary>
+/// <remarks>
+/// A tentacao do <c>skip</c> e real ("nao da para avaliar, entao nao avalio") e recria
+/// exatamente o buraco que este harness fechou duas vezes: gate verde sobre verificacao que
+/// nao aconteceu. E ha razao positiva: em CI, com cache commitada, um miss significa UMA
+/// coisa so — o prompt ou o modelo mudou e ninguem regravou. O miss e o veredito, nao o
+/// obstaculo.
+/// </remarks>
+public sealed class EvalCacheMissTests
+{
+    private static async Task<EvalWorkspace> SeededAsync(params string[] scenarioNames)
+    {
+        var ws = new EvalWorkspace();
+        using var fake = new FakeChatClient
+        {
+            MetadataProviderName = "morph-fake",
+            MetadataDefaultModelId = "modelo-exemplar",
+        };
+
+        foreach (var name in scenarioNames)
+        {
+            ws.WriteScenario("triagem", "acme", name, $"pergunta de {name}", """[ { "kind": "contains", "value": "resposta" } ]""");
+            fake.EnqueueText($"resposta de {name}");
+        }
+
+        await using var refresh = EvalFixture.Create(ws.Options(EvalMode.Refresh), fake);
+        await refresh.RunAllAsync(TestContext.Current.CancellationToken);
+        return ws;
+    }
+
+    [Fact]
+    public async Task AScenarioMissingFromTheCacheFailsByNameInsteadOfCallingTheProvider()
+    {
+        using var ws = await SeededAsync("a-primeiro");
+
+        // Cenario NOVO, que a cache nunca viu — a situacao literal de "mudou o prompt e
+        // ninguem regravou". O prefixo "b-" e deliberado: os cenarios rodam em ordem ordinal
+        // de caminho, e o teste abaixo depende de o cenario BOM ter rodado antes do miss.
+        ws.WriteScenario("triagem", "acme", "b-novo", "pergunta inedita", """[ { "kind": "contains", "value": "resposta" } ]""");
+
+        await using var offline = EvalFixture.Create(ws.Options(EvalMode.Offline));
+        var error = await Assert.ThrowsAsync<EvalCacheMissException>(
+            () => offline.RunAllAsync(TestContext.Current.CancellationToken));
+
+        // O cenario que faltou, e nao "algum cenario".
+        Assert.Equal("triagem.acme.b-novo", error.ScenarioName);
+        Assert.Contains("eval-cache-miss", error.Message, StringComparison.Ordinal);
+
+        // P3: a mensagem carrega o comando de regravacao e o arquivo de credencial esperado.
+        // Um "cache miss" seco mandaria o leitor procurar os dois.
+        Assert.Contains(EvalCacheMissException.RefreshCommand, error.Message, StringComparison.Ordinal);
+        Assert.Contains(".env.evals", error.Message, StringComparison.Ordinal);
+        Assert.Contains(ws.CacheRoot, error.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task TheMissTravelsAsAFAILURE_NeverAsASkippedScenario()
+    {
+        using var ws = await SeededAsync("a-primeiro");
+        ws.WriteScenario("triagem", "acme", "b-novo", "pergunta inedita", """[ { "kind": "contains", "value": "resposta" } ]""");
+
+        // O sumario da SEMEADURA, byte a byte. Ele e a linha de base: o que este teste cobra
+        // e que o run que morreu por miss nao escreva NADA por cima dele.
+        var summaryBeforeTheMiss = File.ReadAllBytes(ws.SummaryPath);
+
+        await using var offline = EvalFixture.Create(ws.Options(EvalMode.Offline));
+        await Assert.ThrowsAsync<EvalCacheMissException>(
+            () => offline.RunAllAsync(TestContext.Current.CancellationToken));
+
+        // Nao ha caminho pelo qual o cenario ausente apareca como avaliado: a contagem so tem
+        // o que de fato resolveu, e o sumario NAO foi reescrito. Um sumario dizendo
+        // "1 cenario, 1 passou, cache warm" aqui seria exatamente a mentira que a excecao
+        // existe para impedir — e o CLI, que le o ARQUIVO, acreditaria nela.
+        Assert.Single(offline.Results);
+        Assert.Equal("triagem.acme.a-primeiro", offline.Results[0].Scenario);
+        Assert.Equal(summaryBeforeTheMiss, File.ReadAllBytes(ws.SummaryPath));
+
+        // E o contador do cliente interno registra a tentativa: a arvore de cache nao
+        // respondeu, e isso e um FATO medido, nao uma inferencia.
+        Assert.Equal(1, offline.Offline!.Invocations);
+    }
+
+    [Fact]
+    public async Task AFailedAssertionMakesTheScenarioREDWithoutAnyCacheMiss()
+    {
+        // A outra metade do contrato: reprovar por conteudo e diferente de reprovar por
+        // cache. Uma so mensagem para os dois casos mandaria o leitor procurar no lugar
+        // errado metade das vezes.
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario("triagem", "acme", "saudacao", "bom dia", """[ { "kind": "contains", "value": "jamais aparece" } ]""");
+
+        using var fake = new FakeChatClient { MetadataProviderName = "morph-fake", MetadataDefaultModelId = "modelo-exemplar" };
+        fake.EnqueueText("Ola!");
+        await using (var refresh = EvalFixture.Create(ws.Options(EvalMode.Refresh), fake))
+        {
+            await refresh.RunAllAsync(TestContext.Current.CancellationToken);
+        }
+
+        await using var offline = EvalFixture.Create(ws.Options(EvalMode.Offline));
+        var summary = await offline.RunAllAsync(TestContext.Current.CancellationToken);
+
+        Assert.Equal(1, summary.Scenarios);
+        Assert.Equal(1, summary.Failed);
+        Assert.Equal(EvalCacheState.Warm, summary.Cache);
+        Assert.Equal(0, summary.Misses);
+        Assert.Contains("FALHOU", offline.Results[0].Outcomes[0].Reason, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task AScenarioWithNoDeterministicAssertionIsNeverGreenByVacuity()
+    {
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario("triagem", "acme", "vazio", "bom dia", "[]");
+
+        using var fake = new FakeChatClient { MetadataProviderName = "morph-fake", MetadataDefaultModelId = "modelo-exemplar" };
+        fake.EnqueueText("Ola!");
+        await using (var refresh = EvalFixture.Create(ws.Options(EvalMode.Refresh), fake))
+        {
+            await refresh.RunAllAsync(TestContext.Current.CancellationToken);
+        }
+
+        await using var offline = EvalFixture.Create(ws.Options(EvalMode.Offline));
+        var summary = await offline.RunAllAsync(TestContext.Current.CancellationToken);
+
+        // Um cenario que nao cobra nada nao pode contar como cobertura. Deixa-lo verde e o
+        // mesmo defeito de um teste vazio — pior aqui, porque ele apareceria na contagem
+        // como se tivesse verificado algo.
+        Assert.Equal(1, summary.Failed);
+        Assert.Equal(0, summary.Passed);
+    }
+}

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

@@ -0,0 +1,157 @@
+using Morph.AiKit.Evals;
+using Morph.AiKit.Tests.Fakes;
+using Xunit;
+
+namespace Morph.AiKit.Tests.Evals;
+
+/// <summary>
+/// O carimbo: por que a arvore de cache precisa dizer sob quais versoes foi gravada.
+/// </summary>
+/// <remarks>
+/// A funcao de hash que produz a chave nao promete estabilidade entre versoes da biblioteca.
+/// Sem carimbo, subir o pin chega como N misses inexplicaveis num dia em que ninguem mexeu
+/// em nada; com carimbo, chega como uma frase que nomeia as DUAS versoes.
+/// </remarks>
+public sealed class EvalCacheStampTests
+{
+    private static readonly FakeClock Today = new(new DateTimeOffset(2026, 9, 8, 12, 0, 0, TimeSpan.Zero));
+
+    private static EvalPin Pin(string pinnedAt = "2026-09-08", string evaluation = "10.9.0") => new(
+        pinnedAt,
+        new Dictionary<string, string>(StringComparer.Ordinal)
+        {
+            ["Microsoft.Extensions.AI"] = "10.9.0",
+            ["Microsoft.Extensions.AI.Evaluation"] = evaluation,
+        });
+
+    private static void Stamp(string root, string pinnedAt = "2026-09-08", string evaluation = "10.9.0")
+        => EvalCacheStamp.Write(root, new EvalCacheStamp
+        {
+            PinnedAt = pinnedAt,
+            Packages = Pin(pinnedAt, evaluation).Packages,
+            Provider = "morph-fake",
+            Model = "modelo-exemplar",
+        });
+
+    [Fact]
+    public void AStampedTreeThatMatchesThePinIsAccepted()
+    {
+        using var ws = new EvalWorkspace();
+        Stamp(ws.CacheRoot);
+
+        var check = EvalCacheStamp.Check(ws.CacheRoot, Pin(), Today);
+
+        Assert.True(check.IsOk);
+        Assert.Equal(EvalStampVerdict.Ok, check.Verdict);
+    }
+
+    [Fact]
+    public void TheStampCarriesThePinDateAndTheEvaluationVersionsItWasWrittenUnder()
+    {
+        using var ws = new EvalWorkspace();
+        Stamp(ws.CacheRoot);
+
+        // Ler de VOLTA do disco, e nao comparar o objeto com ele mesmo: o carimbo e um
+        // artefato, e um teste que so olhasse a instancia em memoria seria um espelho.
+        var read = EvalCacheStamp.Read(ws.CacheRoot);
+
+        Assert.NotNull(read);
+        Assert.Equal("2026-09-08", read!.PinnedAt);
+        Assert.Equal("10.9.0", read.Packages["Microsoft.Extensions.AI.Evaluation"]);
+        Assert.Equal("morph-fake", read.Provider);
+        Assert.Equal(EvalCacheStamp.Writer, read.WrittenBy);
+    }
+
+    [Fact]
+    public void ADivergentStampIsRefusedNamingBOTHVersions()
+    {
+        using var ws = new EvalWorkspace();
+        Stamp(ws.CacheRoot, evaluation: "10.9.0");
+
+        var check = EvalCacheStamp.Check(ws.CacheRoot, Pin(evaluation: "10.11.0"), Today);
+
+        Assert.Equal(EvalStampVerdict.PinMismatch, check.Verdict);
+        Assert.Contains("eval-cache-stale-pin", check.Reason, StringComparison.Ordinal);
+        // Dizer so uma das versoes obriga o leitor a ir buscar a outra.
+        Assert.Contains("gravada 10.9.0", check.Reason, StringComparison.Ordinal);
+        Assert.Contains("pin 10.11.0", check.Reason, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void AMissingStampHasItsOWNReason_DistinctFromADivergentOne()
+    {
+        using var ws = new EvalWorkspace();
+
+        var missing = EvalCacheStamp.Check(ws.CacheRoot, Pin(), Today);
+        Stamp(ws.CacheRoot, evaluation: "10.9.0");
+        var divergent = EvalCacheStamp.Check(ws.CacheRoot, Pin(evaluation: "10.11.0"), Today);
+
+        Assert.Equal(EvalStampVerdict.Missing, missing.Verdict);
+        Assert.Contains("eval-cache-unstamped", missing.Reason, StringComparison.Ordinal);
+
+        // As duas situacoes pedem acoes diferentes: "regrave" versus "regrave PORQUE o
+        // pacote mudou". Um veredito unico devolveria ao leitor a pergunta que o carimbo
+        // existia para responder.
+        Assert.NotEqual(missing.Verdict, divergent.Verdict);
+        Assert.DoesNotContain("eval-cache-stale-pin", missing.Reason, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void AnUnreadableStampIsNotSilentlyTreatedAsAbsent()
+    {
+        using var ws = new EvalWorkspace();
+        File.WriteAllText(EvalCacheStamp.PathFor(ws.CacheRoot), "{ isto nao e json");
+
+        var check = EvalCacheStamp.Check(ws.CacheRoot, Pin(), Today);
+
+        Assert.Equal(EvalStampVerdict.Unreadable, check.Verdict);
+        Assert.Null(EvalCacheStamp.Read(ws.CacheRoot));
+    }
+
+    [Fact]
+    public void APinDatedInTheFutureIsAPinERROR_NeverAFreshCache()
+    {
+        using var ws = new EvalWorkspace();
+        Stamp(ws.CacheRoot, pinnedAt: "2027-01-01");
+
+        var check = EvalCacheStamp.Check(ws.CacheRoot, Pin(pinnedAt: "2027-01-01"), Today);
+
+        // O carimbo CASA com o pin — e mesmo assim reprova, porque a regua esta adulterada.
+        // Uma data no futuro renovaria sozinha qualquer janela medida contra ela.
+        Assert.Equal(EvalStampVerdict.FuturePin, check.Verdict);
+        Assert.Contains("eval-pin-future", check.Reason, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void TheFixtureRefusesToEvaluateASINGLEScenarioUnderABadStamp()
+    {
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario("triagem", "acme", "saudacao", "bom dia", """[ { "kind": "contains", "value": "Ola" } ]""");
+        Stamp(ws.CacheRoot, evaluation: "10.9.0");
+
+        var pin = new EvalPin("2026-09-08", new Dictionary<string, string>(StringComparer.Ordinal)
+        {
+            ["Microsoft.Extensions.AI"] = "10.9.0",
+            ["Microsoft.Extensions.AI.Evaluation"] = "10.11.0",
+        });
+
+        // A recusa acontece na CONSTRUCAO — antes de qualquer cenario. Nao faz sentido pagar
+        // o relogio de uma suite para descobrir no fim que a cache nao servia.
+        var error = Assert.Throws<InvalidOperationException>(
+            () => EvalFixture.Create(ws.Options(EvalMode.Offline, pin), timeProvider: Today));
+
+        Assert.Contains("eval-cache-stale-pin", error.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void RefreshDoesNotDemandAStamp_ItWritesOne()
+    {
+        using var ws = new EvalWorkspace();
+
+        // Cobrar carimbo em modo de escrita tornaria impossivel criar a PRIMEIRA cache.
+        var fixture = EvalFixture.Create(ws.Options(EvalMode.Refresh), new FakeChatClient());
+
+        Assert.True(fixture.StampCheck.IsOk);
+        Assert.False(File.Exists(EvalCacheStamp.PathFor(ws.CacheRoot)));
+    }
+}

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

@@ -0,0 +1,178 @@
+using Morph.AiKit.Evals;
+using Morph.AiKit.Tests.Fakes;
+using Xunit;
+
+namespace Morph.AiKit.Tests.Evals;
+
+/// <summary>
+/// A camada que NOMEIA a falha, testada pelo conteudo do que ela produz.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Este arquivo fecha a setima ocorrencia da mesma classe nesta epic, e a mais ironica: o
+/// mecanismo de <c>Failures</c> nasceu para consertar um eval que mordia ANONIMAMENTE, e
+/// nasceu ele proprio sem par. As tres partes podiam ser desligadas sem matar um teste —
+/// <c>CollectFailures</c> devolvendo lista vazia, o ramo da vacuidade nunca disparando, e o
+/// nome da assercao trocado por um literal — e a suite seguia "165 total, 0 falhou".
+/// </para>
+/// <para>
+/// A causa foi uma unica testemunha automatizada: <c>Assert.Empty(summary.Failures)</c> num
+/// run VERDE. Essa asserção é verdadeira exatamente quando o mecanismo esta morto — ela nao
+/// distingue "nao houve falha" de "falha nenhuma e registrada". Uma lista vazia prova a
+/// ausencia de conteudo, jamais a presenca de capacidade.
+/// </para>
+/// <para>
+/// Por isso aqui nao se assere sobre <c>Failures</c> VAZIA: assere-se sobre o CONTEUDO de
+/// <c>Failures</c> num run que falha de verdade — o par, a mesma forma que fechou o motor de
+/// assercao um andar abaixo.
+/// </para>
+/// </remarks>
+public sealed class EvalFailuresTests
+{
+    /// <summary>Grava a cache do cenario com o texto dado, e devolve o fixture offline pronto.</summary>
+    /// <remarks>
+    /// A cache e semeada pelo <see cref="FakeChatClient"/>, NUNCA por chamada paga: o caminho
+    /// de escrita exercitado e o da biblioteca, e a leitura offline le exatamente o que aquela
+    /// escrita produziu.
+    /// </remarks>
+    private static async Task<EvalRunSummary> RunOfflineAsync(EvalWorkspace ws, params string[] responses)
+    {
+        using var fake = new FakeChatClient
+        {
+            MetadataProviderName = "morph-fake",
+            MetadataDefaultModelId = "modelo-exemplar",
+        };
+
+        foreach (var text in responses)
+        {
+            fake.EnqueueText(text);
+        }
+
+        await using (var refresh = EvalFixture.Create(ws.Options(EvalMode.Refresh), fake))
+        {
+            await refresh.RunAllAsync(TestContext.Current.CancellationToken);
+        }
+
+        await using var offline = EvalFixture.Create(ws.Options(EvalMode.Offline));
+        return await offline.RunAllAsync(TestContext.Current.CancellationToken);
+    }
+
+    [Fact]
+    public async Task AFailedScenarioIsRegisteredWithScenarioAssertionKindAndReason()
+    {
+        // O caso central: uma assercao reprova, e a falha chega ao sumario COM NOME. Sem isso
+        // o veredito viaja como contador — "Expected 0, Actual 1" — e quem le tem de abrir o
+        // dataset para descobrir o que quebrou.
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario(
+            "triagem", "acme", "saudacao", "bom dia",
+            """[ { "name": "cumprimenta", "kind": "contains", "value": "bom dia" } ]""");
+
+        var summary = await RunOfflineAsync(ws, "Boa noite!");
+
+        Assert.Equal(1, summary.Failed);
+
+        var failure = Assert.Single(summary.Failures);
+        Assert.Equal("triagem.acme.saudacao", failure.Scenario);
+        Assert.Equal("cumprimenta", failure.Assertion);
+        Assert.Equal("Contains", failure.Kind);
+        Assert.Contains("FALHOU", failure.Reason, StringComparison.Ordinal);
+        Assert.Contains("bom dia", failure.Reason, StringComparison.Ordinal);
+
+        // A linha legivel, no formato que a rubrica eval-de-modelo.md cita como exemplo.
+        Assert.Contains(
+            "eval-fail: triagem.acme.saudacao",
+            summary.DescribeFailures(),
+            StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task TwoReprovedAssertionsInOneScenarioProduceTWOLinesEachNamingItsOwnRule()
+    {
+        // `Failures` e LISTA, e nao contador, porque as duas linhas dizem coisas diferentes:
+        // uma resposta pode quebrar em mais de uma regua, e isso separa "o prompt mudou" de
+        // "o modelo parou de responder". Se o tipo fosse um booleano, esta distincao morreria.
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario(
+            "triagem", "acme", "saudacao", "bom dia",
+            """
+            [
+              { "name": "cumprimenta", "kind": "contains", "value": "bom dia" },
+              { "name": "sem-dado-pessoal", "kind": "no-pii" }
+            ]
+            """);
+
+        var summary = await RunOfflineAsync(ws, "Boa noite! Fale com lucas@example.com");
+
+        Assert.Equal(1, summary.Failed);
+        Assert.Equal(2, summary.Failures.Count);
+
+        Assert.Contains(summary.Failures, f => f.Assertion == "cumprimenta" && f.Kind == "Contains");
+        Assert.Contains(summary.Failures, f => f.Assertion == "sem-dado-pessoal" && f.Kind == "NoPii");
+
+        // Toda linha nomeia o cenario: uma falha sem cenario obriga a mesma busca que ela
+        // deveria dispensar.
+        Assert.All(summary.Failures, f => Assert.Equal("triagem.acme.saudacao", f.Scenario));
+    }
+
+    [Fact]
+    public async Task AScenarioWithNOAssertionsIsCountedANDNamed()
+    {
+        // O cenario sem assercao nenhuma reprova por VACUIDADE: ele nao cobra nada. Nesse caso
+        // nao existe outcome reprovado para nomear, e sem um ramo proprio ele seria contado em
+        // `Failed` e invisivel em `Failures` — um numero sem frase, que e metade exata do
+        // defeito que este tipo existe para fechar.
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario("triagem", "acme", "vazio", "bom dia", "[]");
+
+        var summary = await RunOfflineAsync(ws, "Bom dia!");
+
+        Assert.Equal(1, summary.Failed);
+
+        var failure = Assert.Single(summary.Failures);
+        Assert.Equal("triagem.acme.vazio", failure.Scenario);
+        Assert.Contains("sem assercao deterministica", failure.Reason, StringComparison.Ordinal);
+
+        // Contado E nomeado: o numero e a frase tem de concordar sempre.
+        Assert.Equal(summary.Failed, summary.Failures.Count);
+    }
+
+    [Fact]
+    public async Task AGreenRunRegistersNoFailureAndSaysSoInWords()
+    {
+        // A reciproca vive AO LADO dos casos que falham de verdade, nunca sozinha: uma suite
+        // cuja unica testemunha e `Assert.Empty` num run verde e verdadeira precisamente
+        // quando o mecanismo esta morto.
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario(
+            "triagem", "acme", "saudacao", "bom dia",
+            """[ { "name": "cumprimenta", "kind": "contains", "value": "bom dia" } ]""");
+
+        var summary = await RunOfflineAsync(ws, "Bom dia! Como posso ajudar?");
+
+        Assert.Equal(0, summary.Failed);
+        Assert.Empty(summary.Failures);
+        Assert.Equal("nenhuma falha de eval registrada", summary.DescribeFailures());
+    }
+
+    [Fact]
+    public async Task TheNamedFailuresSurviveTheROUNDTRIPThroughTheSummaryFileTheCLIReads()
+    {
+        // O sumario e um ARQUIVO: quem consome as falhas e o CLI, do outro lado do disco. Uma
+        // lista que existisse so em memoria seria invisivel exatamente onde precisa ser lida.
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario(
+            "triagem", "acme", "saudacao", "bom dia",
+            """[ { "name": "cumprimenta", "kind": "contains", "value": "bom dia" } ]""");
+
+        await RunOfflineAsync(ws, "Boa noite!");
+
+        var reread = EvalRunSummary.ReadFrom(ws.SummaryPath);
+
+        Assert.NotNull(reread);
+        var failure = Assert.Single(reread!.Failures);
+        Assert.Equal("triagem.acme.saudacao", failure.Scenario);
+        Assert.Equal("cumprimenta", failure.Assertion);
+        Assert.Equal("Contains", failure.Kind);
+    }
+}

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

@@ -0,0 +1,153 @@
+using Microsoft.Extensions.AI.Evaluation.Reporting;
+using Morph.AiKit.Evals;
+using Morph.AiKit.Tests.Fakes;
+using Xunit;
+
+namespace Morph.AiKit.Tests.Evals;
+
+/// <summary>
+/// A prova que decide a feature: <b>com a cache quente, o eval roda sem credencial e sem
+/// rede</b>.
+/// </summary>
+/// <remarks>
+/// Essa frase foi derivada de leitura de fonte antes de existir codigo. Aqui ela vira
+/// medicao: uma arvore de cache e gravada por um fake, o processo troca o cliente interno
+/// por um que RECUSA qualquer chamada, e a suite termina verde. Se o cliente interno fosse
+/// tocado uma unica vez, o contador dele deixaria de ser zero — e nenhuma das assercoes
+/// abaixo passaria.
+/// </remarks>
+public sealed class EvalFixtureTests
+{
+    [Fact]
+    public async Task RefreshWritesTheCacheAndOfflineReadsItBackWithoutInvokingTheInnerClient()
+    {
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario("triagem", "acme", "saudacao", "bom dia", """[ { "kind": "contains", "value": "Ola" } ]""");
+        ws.WriteScenario("triagem", "acme", "handoff", "quero falar com humano", """[ { "kind": "contains", "value": "humano" } ]""");
+
+        // 1) GRAVA a arvore contra o fake — nunca contra uma API paga. O caminho de escrita
+        //    exercitado e o da biblioteca, e a chave e computada pela mesma funcao que a
+        //    leitura vai usar.
+        using var fake = new FakeChatClient
+        {
+            MetadataProviderName = "morph-fake",
+            MetadataDefaultModelId = "modelo-exemplar",
+        };
+        // A ORDEM importa e e a do dataset (ordinal por caminho): "handoff" vem antes de
+        // "saudacao". Enfileirar na ordem alfabetica errada foi como esta suite descobriu
+        // que LoadAll ordena — e a ordem estavel e o que faz duas maquinas gravarem a mesma
+        // arvore de cache.
+        fake.EnqueueText("Encaminhando para um humano agora.").EnqueueText("Ola! Bom dia.");
+
+        await using (var refresh = EvalFixture.Create(ws.Options(EvalMode.Refresh), fake))
+        {
+            var written = await refresh.RunAllAsync(TestContext.Current.CancellationToken);
+            Assert.Equal(2, written.Scenarios);
+            Assert.Equal(2, written.Passed);
+            Assert.Equal(EvalCacheState.Cold, written.Cache);
+        }
+
+        Assert.Equal(2, fake.CallCount);
+        Assert.True(File.Exists(EvalCacheStamp.PathFor(ws.CacheRoot)), "o refresh tem de deixar o carimbo na raiz da cache");
+
+        // 2) LE offline. O cliente interno agora RECUSA: se a cache nao respondesse, este
+        //    bloco lancaria EvalCacheMissException em vez de terminar verde.
+        await using var offline = EvalFixture.Create(ws.Options(EvalMode.Offline));
+        var summary = await offline.RunAllAsync(TestContext.Current.CancellationToken);
+
+        Assert.Equal(2, summary.Scenarios);
+        Assert.Equal(2, summary.Passed);
+        Assert.Equal(0, summary.Failed);
+        Assert.Equal(EvalCacheState.Warm, summary.Cache);
+        Assert.Equal(0, summary.Misses);
+        Assert.Equal("ok", summary.Stamp);
+        Assert.Equal(0, offline.Offline!.Invocations);
+
+        // 3) O fake nao foi tocado de novo: a leitura offline nao passou por ele nem por
+        //    acidente (ele esta noutro processo logico, mas a contagem prova a intencao).
+        Assert.Equal(2, fake.CallCount);
+    }
+
+    [Fact]
+    public async Task TheSummaryIsWrittenToThePathTheCallerDictates()
+    {
+        using var ws = new EvalWorkspace();
+        ws.WriteScenario("triagem", "acme", "saudacao", "bom dia", """[ { "kind": "contains", "value": "Ola" } ]""");
+
+        using var fake = new FakeChatClient { MetadataProviderName = "morph-fake", MetadataDefaultModelId = "modelo-exemplar" };
+        fake.EnqueueText("Ola!");
+        await using (var refresh = EvalFixture.Create(ws.Options(EvalMode.Refresh), fake))
+        {
+            await refresh.RunAllAsync(TestContext.Current.CancellationToken);
+        }
+
+        await using var offline = EvalFixture.Create(ws.Options(EvalMode.Offline));
+        await offline.RunAllAsync(TestContext.Current.CancellationToken);
+
+        // Ler de volta o ARQUIVO, e nao o objeto em memoria: o contrato com o CLI e o
+        // arquivo, e um teste que so olhasse o objeto seria um espelho do gerador.
+        var reread = EvalRunSummary.ReadFrom(ws.SummaryPath);
+        Assert.NotNull(reread);
+        Assert.Equal(1, reread!.Scenarios);
+        Assert.Equal(EvalCacheState.Warm, reread.Cache);
+        Assert.Equal("morph-fake", reread.Provider);
+        Assert.Equal("modelo-exemplar", reread.Model);
+    }
+
+    [Fact]
+    public void ATimeToLiveBelowOneYearIsRefusedWithTheReasonInTheMessage()
+    {
+        using var ws = new EvalWorkspace();
+        var options = ws.Options(EvalMode.Offline) with { TimeToLive = TimeSpan.FromDays(14) };
+
+        var error = Assert.Throws<ArgumentOutOfRangeException>(() => EvalFixture.Create(options));
+
+        Assert.Contains("eval-cache-ttl-too-short", error.Message, StringComparison.Ordinal);
+        // A mensagem tem de dizer POR QUE, e nao so que o numero e pequeno: a expiracao apaga
+        // o diretorio da chave durante a LEITURA.
+        Assert.Contains("DESTRUTIVA NA LEITURA", error.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void TheLibraryDefaultTimeToLiveWouldExpireACommittedCacheWithinWeeks()
+    {
+        // MEDIDO, nao lembrado: e este fato que torna o TTL explicito obrigatorio. Se um dia
+        // a biblioteca subir o default para alem do piso do kit, este teste morre e a
+        // exigencia pode ser rediscutida com um numero na mao.
+        Assert.True(
+            Defaults.DefaultTimeToLiveForCacheEntries < EvalCacheOptions.MinimumTimeToLive,
+            $"o default da biblioteca e {Defaults.DefaultTimeToLiveForCacheEntries.TotalDays:0} dias, "
+          + $"o piso do kit e {EvalCacheOptions.MinimumTimeToLive.TotalDays:0}");
+        Assert.Equal(14, Defaults.DefaultTimeToLiveForCacheEntries.TotalDays);
+    }
+
+    [Fact]
+    public void AWriteModeWithoutARealClientIsRefusedByName()
+    {
+        using var ws = new EvalWorkspace();
+
+        var error = Assert.Throws<InvalidOperationException>(
+            () => EvalFixture.Create(ws.Options(EvalMode.Refresh), liveClient: null));
+
+        Assert.Contains("eval-live-client-missing", error.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task AnEmptyDatasetIsAFailureAndNeverAGreenRunOfZeroScenarios()
+    {
+        using var ws = new EvalWorkspace();
+        EvalCacheStamp.Write(ws.CacheRoot, new EvalCacheStamp
+        {
+            PinnedAt = EvalWorkspace.Pin.PinnedAt,
+            Packages = EvalWorkspace.Pin.Packages,
+            Provider = "morph-fake",
+            Model = "modelo-exemplar",
+        });
+
+        await using var fixture = EvalFixture.Create(ws.Options(EvalMode.Offline));
+        var error = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => fixture.RunAllAsync(TestContext.Current.CancellationToken));
+
+        Assert.Contains("eval-empty-run", error.Message, StringComparison.Ordinal);
+    }
+}