@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,246 @@
+using System.Text;
+using System.Text.Json;
+using System.Text.RegularExpressions;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.AI.Evaluation;
+
+namespace Morph.AiKit.Evals;
+
+/// <summary>O que uma assercao deterministica pergunta a uma resposta.</summary>
+/// <remarks>
+/// A lista e curta de proposito. Toda entrada aqui e uma propriedade que se decide sem
+/// julgamento: ou o texto contem, ou nao contem; ou a ferramenta foi escolhida, ou nao foi.
+/// Uma "assercao" que precisasse de um modelo para decidir seria juizo, e juizo nao reprova
+/// sozinho neste kit.
+/// </remarks>
+public enum EvalAssertionKind
+{
+    /// <summary>O texto da resposta contem o valor (ignorando caixa).</summary>
+    Contains = 0,
+
+    /// <summary>O texto da resposta NAO contem o valor (ignorando caixa).</summary>
+    NotContains = 1,
+
+    /// <summary>A resposta e um objeto JSON e tem a chave de topo indicada em <c>Target</c>.</summary>
+    JsonHasKey = 2,
+
+    /// <summary>A resposta nao carrega dado pessoal nas formas que o kit sabe reconhecer.</summary>
+    NoPii = 3,
+
+    /// <summary>A resposta escolheu a ferramenta nomeada em <c>Target</c>.</summary>
+    ToolCalled = 4,
+
+    /// <summary>A ferramenta <c>Target</c> foi chamada com o argumento <c>Value</c> no formato <c>chave=valor</c>.</summary>
+    ToolArgument = 5,
+}
+
+/// <summary>Veredito de uma assercao: o booleano e a frase que o explica.</summary>
+/// <param name="Passed">Se a propriedade se sustentou.</param>
+/// <param name="Reason">Por que — nomeando o que foi procurado, para nao mandar o leitor adivinhar.</param>
+public sealed record EvalAssertionOutcome(bool Passed, string Reason)
+{
+    /// <summary>Nome da assercao que produziu este veredito.</summary>
+    /// <remarks>
+    /// Carimbado por <see cref="EvalAssertion.Evaluate"/>. Existe porque uma falha que chega a
+    /// jusante como contador ("Expected 0, Actual 1") nao diz O QUE quebrou: quem le precisa
+    /// abrir o dataset e adivinhar. Um eval que morde anonimamente obriga a investigacao que
+    /// ele deveria dispensar.
+    /// </remarks>
+    public string? Assertion { get; init; }
+
+    /// <summary>O tipo da assercao que julgou — a REGUA, nao so o nome dela.</summary>
+    public EvalAssertionKind? Kind { get; init; }
+}
+
+/// <summary>
+/// A assercao deterministica: o unico tipo de avaliador que REPROVA neste kit.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que so ela decide.</b> Os avaliadores de qualidade da biblioteca sao juizo de LLM,
+/// e juizo de LLM varia. Um gate que reprovasse por variancia de juiz reintroduziria o
+/// FLAKY que faz suites de eval serem desligadas do CI — e um no de eval desligado nao
+/// verifica nada. Entao a divisao e explicita: assercao deterministica decide; qualidade e
+/// numero reportado.
+/// </para>
+/// <para>
+/// <b>Ela e um <see cref="IEvaluator"/> de verdade</b>, e nao um predicado aplicado por
+/// fora, para que a metrica caia no MESMO relatorio que as de qualidade. Um resultado que
+/// vivesse fora do relatorio precisaria de um segundo lugar para ser lido, e o segundo lugar
+/// e onde as duas verdades comecam.
+/// </para>
+/// </remarks>
+public sealed record EvalAssertion : IEvaluator
+{
+    /// <summary>
+    /// Formas de dado pessoal que o kit reconhece. Deliberadamente poucas e literais: um
+    /// detector de PII abrangente e um projeto proprio, e prometer mais do que se mede seria
+    /// pior do que nao prometer. Sem <c>\b</c> em nenhum padrao — a fronteira de palavra do
+    /// .NET tambem nao trata acento como letra em toda cultura, e um padrao que nao casa e
+    /// pior que um padrao que nao existe.
+    /// </summary>
+    private static readonly (string Label, Regex Pattern)[] PiiPatterns =
+    [
+        ("e-mail", new Regex("[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+[.][A-Za-z]{2,}", RegexOptions.CultureInvariant)),
+        ("CPF", new Regex("[0-9]{3}[.][0-9]{3}[.][0-9]{3}-[0-9]{2}", RegexOptions.CultureInvariant)),
+        ("telefone", new Regex("[(][0-9]{2}[)] ?[0-9]{4,5}-[0-9]{4}", RegexOptions.CultureInvariant)),
+    ];
+
+    /// <summary>
+    /// Nome da metrica. UNICO dentro de um cenario: a biblioteca indexa metricas por nome, e
+    /// duas assercoes homonimas fariam a segunda sobrescrever a primeira em silencio — um
+    /// cenario que parece cobrar duas propriedades e cobra uma.
+    /// </summary>
+    public required string Name { get; init; }
+
+    /// <summary>O que esta assercao pergunta.</summary>
+    public required EvalAssertionKind Kind { get; init; }
+
+    /// <summary>Chave JSON ou nome de ferramenta, conforme o <see cref="Kind"/>.</summary>
+    public string? Target { get; init; }
+
+    /// <summary>Texto procurado, ou <c>chave=valor</c> em <see cref="EvalAssertionKind.ToolArgument"/>.</summary>
+    public string? Value { get; init; }
+
+    /// <inheritdoc />
+    public IReadOnlyCollection<string> EvaluationMetricNames => [Name];
+
+    /// <summary>Aplica a assercao a uma resposta. Puro: nao le disco, nao le ambiente, nao chama rede.</summary>
+    public EvalAssertionOutcome Evaluate(ChatResponse response)
+    {
+        ArgumentNullException.ThrowIfNull(response);
+
+        var text = TextOf(response);
+
+        var outcome = Kind switch
+        {
+            EvalAssertionKind.Contains => Judge(
+                Value is not null && text.Contains(Value, StringComparison.OrdinalIgnoreCase),
+                $"a resposta deveria conter \"{Value}\""),
+
+            EvalAssertionKind.NotContains => Judge(
+                Value is not null && !text.Contains(Value, StringComparison.OrdinalIgnoreCase),
+                $"a resposta nao deveria conter \"{Value}\""),
+
+            EvalAssertionKind.JsonHasKey => JudgeJsonKey(text),
+
+            EvalAssertionKind.NoPii => JudgeNoPii(text),
+
+            EvalAssertionKind.ToolCalled => Judge(
+                Target is not null && ToolCalls(response).Any(c => NameMatches(c, Target)),
+                $"a resposta deveria escolher a ferramenta \"{Target}\""),
+
+            EvalAssertionKind.ToolArgument => JudgeToolArgument(response),
+
+            _ => new EvalAssertionOutcome(false, $"tipo de assercao desconhecido: {Kind}"),
+        };
+
+        // Carimba QUEM julgou. O veredito sozinho e um booleano; com o nome e a regua ele vira
+        // uma frase que nomeia o defeito sem obrigar ninguem a abrir o dataset.
+        return outcome with { Assertion = Name, Kind = this.Kind };
+    }
+
+    /// <inheritdoc />
+    public ValueTask<EvaluationResult> EvaluateAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatResponse modelResponse,
+        ChatConfiguration? chatConfiguration = null,
+        IEnumerable<EvaluationContext>? additionalContext = null,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(modelResponse);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        var outcome = Evaluate(modelResponse);
+        var metric = new BooleanMetric(Name, outcome.Passed, outcome.Reason);
+        return ValueTask.FromResult(new EvaluationResult(metric));
+    }
+
+    /// <summary>Texto concatenado da resposta — a superficie que as assercoes de texto leem.</summary>
+    internal static string TextOf(ChatResponse response)
+    {
+        var sb = new StringBuilder();
+        foreach (var message in response.Messages)
+        {
+            foreach (var content in message.Contents.OfType<TextContent>())
+            {
+                sb.Append(content.Text);
+            }
+        }
+
+        return sb.ToString();
+    }
+
+    private static IEnumerable<FunctionCallContent> ToolCalls(ChatResponse response)
+        => response.Messages.SelectMany(m => m.Contents).OfType<FunctionCallContent>();
+
+    private static bool NameMatches(FunctionCallContent call, string target)
+        => string.Equals(call.Name, target, StringComparison.OrdinalIgnoreCase);
+
+    private EvalAssertionOutcome Judge(bool passed, string expectation)
+        => new(passed, passed ? $"OK: {expectation}" : $"FALHOU: {expectation}");
+
+    private EvalAssertionOutcome JudgeJsonKey(string text)
+    {
+        if (Target is null)
+        {
+            return new EvalAssertionOutcome(false, "FALHOU: assercao json-has-key sem chave declarada");
+        }
+
+        try
+        {
+            using var doc = JsonDocument.Parse(text);
+            if (doc.RootElement.ValueKind != JsonValueKind.Object)
+            {
+                return new EvalAssertionOutcome(false, $"FALHOU: a resposta e JSON mas nao um objeto ({doc.RootElement.ValueKind})");
+            }
+
+            var has = doc.RootElement.TryGetProperty(Target, out _);
+            return Judge(has, $"o objeto JSON da resposta deveria ter a chave \"{Target}\"");
+        }
+        catch (JsonException e)
+        {
+            return new EvalAssertionOutcome(false, $"FALHOU: a resposta nao e JSON valido ({e.Message})");
+        }
+    }
+
+    private EvalAssertionOutcome JudgeNoPii(string text)
+    {
+        var found = PiiPatterns.Where(p => p.Pattern.IsMatch(text)).Select(p => p.Label).ToList();
+        return found.Count == 0
+            ? new EvalAssertionOutcome(true, "OK: nenhuma forma conhecida de dado pessoal na resposta")
+            : new EvalAssertionOutcome(false, $"FALHOU: a resposta carrega dado pessoal ({string.Join(", ", found)})");
+    }
+
+    private EvalAssertionOutcome JudgeToolArgument(ChatResponse response)
+    {
+        if (Target is null || Value is null)
+        {
+            return new EvalAssertionOutcome(false, "FALHOU: assercao tool-argument exige ferramenta e chave=valor");
+        }
+
+        var split = Value.IndexOf('=', StringComparison.Ordinal);
+        if (split <= 0)
+        {
+            return new EvalAssertionOutcome(false, $"FALHOU: \"{Value}\" nao esta na forma chave=valor");
+        }
+
+        var key = Value[..split];
+        var expected = Value[(split + 1)..];
+
+        foreach (var call in ToolCalls(response).Where(c => NameMatches(c, Target)))
+        {
+            if (call.Arguments is null || !call.Arguments.TryGetValue(key, out var actual))
+            {
+                continue;
+            }
+
+            if (string.Equals(Convert.ToString(actual, System.Globalization.CultureInfo.InvariantCulture), expected, StringComparison.OrdinalIgnoreCase))
+            {
+                return new EvalAssertionOutcome(true, $"OK: \"{Target}\" foi chamada com {key}={expected}");
+            }
+        }
+
+        return new EvalAssertionOutcome(false, $"FALHOU: \"{Target}\" deveria ser chamada com {key}={expected}");
+    }
+}

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

@@ -0,0 +1,57 @@
+namespace Morph.AiKit.Evals;
+
+/// <summary>
+/// Lancada quando um cenario de eval NAO estava na cache e o modo corrente e
+/// <see cref="EvalMode.Offline"/> — o unico caminho pelo qual a suite tocaria a rede.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que uma excecao, e nao um resultado.</b> A regra do kit e "excecao nunca como
+/// fluxo de controle"; esta e a excecao de CONTRATO que a propria regra admite. O ponto de
+/// deteccao e o <see cref="OfflineChatClient"/>, que implementa <c>IChatClient</c> — uma
+/// interface de terceiro cuja assinatura devolve <c>Task&lt;ChatResponse&gt;</c> e nao tem
+/// onde carregar um veredito. Devolver uma resposta vazia ali seria pior do que lancar:
+/// o eval ficaria VERDE sobre um cenario que ninguem avaliou, que e exatamente o defeito
+/// (gate verde sobre verificacao que nao aconteceu) que esta feature existe para fechar.
+/// </para>
+/// <para>
+/// <b>A mensagem e o produto.</b> Em CI, com a cache commitada, um miss significa uma coisa
+/// so: o prompt ou o modelo mudou e ninguem regravou. Entao a mensagem nomeia as quatro
+/// coisas que o leitor precisa para agir sem abrir o codigo — o cenario, o caminho da
+/// cache, o comando de regravacao e o arquivo de credencial esperado. Um "cache miss"
+/// seco mandaria o leitor procurar as quatro.
+/// </para>
+/// </remarks>
+public sealed class EvalCacheMissException : Exception
+{
+    /// <summary>Comando literal que regrava a arvore de cache. Nunca implicito, nunca automatico.</summary>
+    public const string RefreshCommand = "morph-spec verify {feature} --refresh-cache";
+
+    /// <summary>Cria a excecao com todos os dados que a mensagem precisa nomear.</summary>
+    /// <param name="scenarioName">O cenario que faltou na cache.</param>
+    /// <param name="cachePath">Raiz da arvore de cache consultada.</param>
+    /// <param name="envFile">Arquivo (gitignored) de onde a credencial viria numa regravacao.</param>
+    public EvalCacheMissException(string scenarioName, string cachePath, string envFile)
+        : base(BuildMessage(scenarioName, cachePath, envFile))
+    {
+        ScenarioName = scenarioName;
+        CachePath = cachePath;
+        EnvFile = envFile;
+    }
+
+    /// <summary>O cenario que faltou na cache.</summary>
+    public string ScenarioName { get; }
+
+    /// <summary>Raiz da arvore de cache consultada.</summary>
+    public string CachePath { get; }
+
+    /// <summary>Arquivo de credencial esperado por uma regravacao.</summary>
+    public string EnvFile { get; }
+
+    private static string BuildMessage(string scenarioName, string cachePath, string envFile)
+        => $"eval-cache-miss: o cenario \"{scenarioName}\" nao esta na cache em \"{cachePath}\" "
+         + "e o modo corrente e offline (nenhuma chamada de rede sera feita). "
+         + $"Em CI isto significa que o prompt ou o modelo mudou e a cache nao foi regravada. "
+         + $"Para regravar: {RefreshCommand} — a credencial vem de \"{envFile}\", "
+         + "que e gitignored e nunca viaja no config commitado.";
+}

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

@@ -0,0 +1,78 @@
+namespace Morph.AiKit.Evals;
+
+/// <summary>
+/// Tudo o que o <see cref="EvalFixture"/> precisa saber, e nada que ele possa adivinhar.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b><see cref="TimeToLive"/> nao tem valor default, e isso e o item mais importante deste
+/// tipo.</b> O default da biblioteca e de 14 dias E A EXPIRACAO E DESTRUTIVA NA LEITURA: ao
+/// achar uma entrada vencida, o provedor APAGA o diretorio da chave e devolve nulo. Uma
+/// cache commitada com o default se apaga sozinha ao ser lida, duas semanas depois de
+/// gravada — e o sintoma chega como miss em massa (e arvore suja no <c>git status</c>) num
+/// dia em que ninguem mexeu em nada. Por isso o valor e obrigatorio aqui e o fixture recusa
+/// qualquer coisa abaixo de <see cref="MinimumTimeToLive"/>.
+/// </para>
+/// <para>
+/// <b><see cref="ProviderName"/> e <see cref="DefaultModelId"/> entram na chave de cache</b>
+/// e por isso viajam como configuracao, nao como constante: eles precisam reproduzir o run
+/// que GRAVOU a arvore. O endpoint nao entra na chave (medido na v10.9.0), que e o que
+/// permite ao cliente offline nao ter endpoint algum.
+/// </para>
+/// </remarks>
+public sealed record EvalCacheOptions
+{
+    /// <summary>
+    /// Piso do tempo de vida das entradas. Um ano nao e um numero bonito: e o menor prazo
+    /// que garante que uma cache commitada sobreviva a um ciclo de release sem se apagar
+    /// durante uma leitura.
+    /// </summary>
+    public static readonly TimeSpan MinimumTimeToLive = TimeSpan.FromDays(365);
+
+    /// <summary>Raiz da arvore de cache. COMMITADA.</summary>
+    public required string CacheRoot { get; init; }
+
+    /// <summary>
+    /// Raiz dos resultados de execucao. FORA da arvore commitada — por construcao, e nao por
+    /// um <c>.gitignore</c> dentro de um diretorio commitado (regra de ignore ali e regra que
+    /// a proxima pessoa remove sem entender). Os resultados carregam latencia medida por
+    /// cronometro, uso de tokens e o flag de cache hit: commita-los e diff garantido em toda
+    /// rodada, sem sinal nenhum.
+    /// </summary>
+    public required string ResultsRoot { get; init; }
+
+    /// <summary>Raiz do dataset versionado, em <c>{agente}/{tenant}/{cenario}.json</c>.</summary>
+    public required string DatasetRoot { get; init; }
+
+    /// <summary>Tempo de vida das entradas. Obrigatorio, sempre — ver as observacoes do tipo.</summary>
+    public required TimeSpan TimeToLive { get; init; }
+
+    /// <summary>O <c>ProviderName</c> que entra na chave de cache.</summary>
+    public required string ProviderName { get; init; }
+
+    /// <summary>O <c>DefaultModelId</c> que entra na chave de cache. Nulo e um valor.</summary>
+    public string? DefaultModelId { get; init; }
+
+    /// <summary>De onde a resposta pode vir nesta execucao.</summary>
+    public required EvalMode Mode { get; init; }
+
+    /// <summary>
+    /// Onde o sumario JSON e escrito. O CAMINHO E DITADO PELO CHAMADOR (o CLI escolhe um
+    /// arquivo temporario) para que dois nos de eval no mesmo <c>verify</c> nao colidam.
+    /// Nulo quando ninguem quer sumario — rodar sem sumario e legitimo, inventar um caminho
+    /// nao e.
+    /// </summary>
+    public string? SummaryPath { get; init; }
+
+    /// <summary>
+    /// Arquivo (gitignored) de onde a credencial viria numa regravacao. So aparece em
+    /// mensagem de erro; o fixture nunca o le.
+    /// </summary>
+    public string EnvFile { get; init; } = ".env.evals";
+
+    /// <summary>
+    /// O pin corrente, como o CLI o entregou. Nulo desliga a checagem de carimbo — util para
+    /// um projeto que constroi o fixture a mao, e explicitamente NAO o caminho do CLI.
+    /// </summary>
+    public EvalPin? Pin { get; init; }
+}

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

@@ -0,0 +1,225 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Morph.AiKit.Evals;
+
+/// <summary>O veredito de um carimbo de cache — quatro estados, nunca um booleano.</summary>
+/// <remarks>
+/// <c>Missing</c> e <c>PinMismatch</c> sao SEPARADOS de proposito: as duas situacoes pedem
+/// acoes diferentes. A primeira e "regrave"; a segunda e "regrave <b>porque o pacote
+/// mudou</b>". Colapsa-las num unico "carimbo invalido" devolve ao leitor a pergunta que o
+/// carimbo existia para responder.
+/// </remarks>
+public enum EvalStampVerdict
+{
+    /// <summary>Carimbo presente e de acordo com o pin corrente.</summary>
+    Ok = 0,
+
+    /// <summary>Nao ha carimbo: cache anterior a esta feature, ou diretorio criado a mao.</summary>
+    Missing = 1,
+
+    /// <summary>Ha um arquivo, mas ele nao e JSON legivel no formato do carimbo.</summary>
+    Unreadable = 2,
+
+    /// <summary>As versoes gravadas divergem do pin corrente — a chave de cache pode ter mudado.</summary>
+    PinMismatch = 3,
+
+    /// <summary>O <c>pinnedAt</c> do pin corrente esta no futuro. Erro de pin, jamais cache fresca.</summary>
+    FuturePin = 4,
+}
+
+/// <summary>Resultado de <see cref="EvalCacheStamp.Check"/>: veredito mais a frase que o explica.</summary>
+/// <param name="Verdict">O estado apurado.</param>
+/// <param name="Reason">
+/// Frase pronta para o relatorio. Nos dois vereditos que nomeiam versoes, ela cita AS DUAS
+/// (a gravada e a do pin) — dizer so uma obriga o leitor a ir buscar a outra.
+/// </param>
+public sealed record EvalCacheStampCheck(EvalStampVerdict Verdict, string Reason)
+{
+    /// <summary>Atalho de leitura: o veredito unico que permite avaliar cenario.</summary>
+    public bool IsOk => Verdict == EvalStampVerdict.Ok;
+}
+
+/// <summary>
+/// O pin, do jeito que o fixture o recebe: data de apuracao mais pacote-para-versao.
+/// </summary>
+/// <remarks>
+/// Achatado (nome para versao) e nao a forma completa de <c>framework/ai-pin.json</c>
+/// porque quem o produz e o CLI, na variavel <c>MORPH_EVAL_PIN</c>, e o kit nao le o pin do
+/// disco: um segundo parser de <c>ai-pin.json</c> e como as duas verdades comecam. Aqui
+/// entram apenas os pacotes que decidem o FORMATO da cache — a familia
+/// <c>Microsoft.Extensions.AI</c> e as tres de Evaluation. Subir o provider da OpenAI nao
+/// invalida uma arvore de cache, e um carimbo que reagisse a isso reprovaria por nada.
+/// </remarks>
+/// <param name="PinnedAt">Data ISO em que um humano conferiu as versoes.</param>
+/// <param name="Packages">Nome do pacote para versao exata.</param>
+public sealed record EvalPin(
+    [property: JsonPropertyName("pinnedAt")] string PinnedAt,
+    [property: JsonPropertyName("packages")] IReadOnlyDictionary<string, string> Packages);
+
+/// <summary>
+/// O carimbo que fica na raiz da arvore de cache commitada, e a regra que o julga.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que existe.</b> A funcao de hash que produz a chave de cache nao promete ser
+/// estavel entre versoes da biblioteca — a propria biblioteca carrega um numero de versao
+/// de cache interno, para invalidar tudo quando o formato muda. Ou seja: SUBIR O PIN PODE
+/// INVALIDAR A ARVORE INTEIRA. Sem carimbo isso chega como N misses inexplicaveis num dia
+/// em que ninguem mexeu em nada. Com carimbo, chega como uma frase que nomeia as duas
+/// versoes e o comando de regravacao.
+/// </para>
+/// <para>
+/// <b>Ele nao substitui a leitura da cache</b> — a chave continua sendo computada pela
+/// biblioteca. Ele responde antes, e de graca, a pergunta cuja resposta cara seria "rodou a
+/// suite inteira para descobrir que a cache nao servia".
+/// </para>
+/// </remarks>
+public sealed record EvalCacheStamp
+{
+    /// <summary>Nome do arquivo, na raiz de <c>cachePath</c>. Uma unica grafia.</summary>
+    public const string FileName = ".morph-eval-cache.json";
+
+    /// <summary>Quem grava. Um carimbo de outra origem e um carimbo que ninguem mantem.</summary>
+    public const string Writer = "morph-eval-fixture";
+
+    private static readonly JsonSerializerOptions Json = new()
+    {
+        WriteIndented = true,
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+    };
+
+    /// <summary>O <c>pinnedAt</c> vigente quando a arvore foi gravada.</summary>
+    [JsonPropertyName("pinnedAt")]
+    public required string PinnedAt { get; init; }
+
+    /// <summary>As versoes de pacote sob as quais a arvore foi gravada.</summary>
+    [JsonPropertyName("packages")]
+    public required IReadOnlyDictionary<string, string> Packages { get; init; }
+
+    /// <summary>O <c>ProviderName</c> que entrou na chave.</summary>
+    [JsonPropertyName("provider")]
+    public required string Provider { get; init; }
+
+    /// <summary>O <c>DefaultModelId</c> que entrou na chave. Nulo e um valor, nao um erro.</summary>
+    [JsonPropertyName("model")]
+    public string? Model { get; init; }
+
+    /// <summary>Quem gravou o carimbo.</summary>
+    [JsonPropertyName("writtenBy")]
+    public string WrittenBy { get; init; } = Writer;
+
+    /// <summary>Caminho do arquivo de carimbo dentro de uma raiz de cache.</summary>
+    public static string PathFor(string cacheRoot)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(cacheRoot);
+        return Path.Combine(cacheRoot, FileName);
+    }
+
+    /// <summary>Grava o carimbo. Cria a raiz se ela ainda nao existe.</summary>
+    public static void Write(string cacheRoot, EvalCacheStamp stamp)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(cacheRoot);
+        ArgumentNullException.ThrowIfNull(stamp);
+
+        Directory.CreateDirectory(cacheRoot);
+
+        // Quebras de linha normalizadas para LF e uma quebra final: o carimbo e um arquivo
+        // COMMITADO. Sem isso ele produziria diff que nao e diff — CRLF numa maquina, LF
+        // noutra, e nenhuma quebra no fim em lugar nenhum.
+        var json = JsonSerializer.Serialize(stamp, Json).ReplaceLineEndings("\n");
+        File.WriteAllText(PathFor(cacheRoot), json + "\n");
+    }
+
+    /// <summary>
+    /// Le o carimbo. Devolve <c>null</c> quando o arquivo nao existe OU nao parseia —
+    /// <see cref="Check"/> e quem distingue os dois casos, porque so ela tem as palavras.
+    /// </summary>
+    public static EvalCacheStamp? Read(string cacheRoot)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(cacheRoot);
+
+        var path = PathFor(cacheRoot);
+        if (!File.Exists(path))
+        {
+            return null;
+        }
+
+        try
+        {
+            return JsonSerializer.Deserialize<EvalCacheStamp>(File.ReadAllText(path), Json);
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+
+    /// <summary>
+    /// O carimbo desta arvore contra o pin corrente.
+    /// </summary>
+    /// <param name="cacheRoot">Raiz da arvore de cache.</param>
+    /// <param name="pin">O pin corrente, como o CLI o entregou.</param>
+    /// <param name="timeProvider">
+    /// Relogio injetado — a comparacao de <c>pinnedAt</c> com hoje e uma leitura de relogio,
+    /// e um teste que dependesse do relogio da maquina mudaria de veredito na virada do dia.
+    /// </param>
+    public static EvalCacheStampCheck Check(string cacheRoot, EvalPin pin, TimeProvider timeProvider)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(cacheRoot);
+        ArgumentNullException.ThrowIfNull(pin);
+        ArgumentNullException.ThrowIfNull(timeProvider);
+
+        // O pin vem ANTES do carimbo: um pin com data no futuro renova sozinho qualquer
+        // janela medida contra ele, e comparar um carimbo contra uma regua adulterada
+        // produziria um "ok" que nao significa nada.
+        var today = timeProvider.GetUtcNow().UtcDateTime.ToString("yyyy-MM-dd", System.Globalization.CultureInfo.InvariantCulture);
+        if (string.CompareOrdinal(pin.PinnedAt, today) > 0)
+        {
+            return new EvalCacheStampCheck(
+                EvalStampVerdict.FuturePin,
+                $"eval-pin-future: o pin corrente declara pinnedAt {pin.PinnedAt}, adiante de hoje ({today}). "
+              + "Data no futuro e erro de pin, nunca cache fresca — corrija framework/ai-pin.json.");
+        }
+
+        var path = PathFor(cacheRoot);
+        if (!File.Exists(path))
+        {
+            return new EvalCacheStampCheck(
+                EvalStampVerdict.Missing,
+                $"eval-cache-unstamped: nao ha {FileName} em \"{cacheRoot}\". "
+              + "Uma arvore de cache sem carimbo nao diz sob quais versoes foi gravada — "
+              + $"regrave com `{EvalCacheMissException.RefreshCommand}`.");
+        }
+
+        var stamp = Read(cacheRoot);
+        if (stamp is null)
+        {
+            return new EvalCacheStampCheck(
+                EvalStampVerdict.Unreadable,
+                $"eval-cache-unstamped: {FileName} existe em \"{cacheRoot}\" mas nao e um carimbo legivel. "
+              + $"Regrave com `{EvalCacheMissException.RefreshCommand}`.");
+        }
+
+        var divergent = new List<string>();
+        foreach (var (name, expected) in pin.Packages.OrderBy(x => x.Key, StringComparer.Ordinal))
+        {
+            var recorded = stamp.Packages.TryGetValue(name, out var v) ? v : null;
+            if (!string.Equals(recorded, expected, StringComparison.Ordinal))
+            {
+                divergent.Add($"{name}: gravada {recorded ?? "(ausente)"} vs pin {expected}");
+            }
+        }
+
+        if (divergent.Count > 0)
+        {
+            return new EvalCacheStampCheck(
+                EvalStampVerdict.PinMismatch,
+                $"eval-cache-stale-pin: a cache em \"{cacheRoot}\" foi gravada sob versoes que divergem do pin corrente "
+              + $"({string.Join("; ", divergent)}). A chave de cache nao promete sobreviver a uma troca de versao — "
+              + $"regrave com `{EvalCacheMissException.RefreshCommand}`.");
+        }
+
+        return new EvalCacheStampCheck(EvalStampVerdict.Ok, $"carimbo de acordo com o pin {pin.PinnedAt}");
+    }
+}