@polymorphism-tech/morph-spec 8.38.0 → 8.41.0

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/ConversationStore.cs

@@ -3,54 +3,15 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Conversation;
 
-/// <summary>
-/// O <see cref="ChatHistoryProvider"/> da casa: o historico de conversa vive no acervo
-/// <b>do projeto</b> (<see cref="IConversationStore"/>), nao dentro da
-/// <see cref="AgentSession"/>.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>A decisao que este arquivo torna compilavel.</b> O caminho embutido do MAF
-/// (<c>InMemoryChatHistoryProvider</c>) guarda a conversa no estado da sessao, o que resolve
-/// um chat de demonstracao e nao resolve um CRM multi-tenant: a conversa precisa sobreviver
-/// ao restart, ser lida por relatorio, ser filtrada por tenant e ser apagada a pedido do
-/// titular. Aqui a <see cref="AgentSession"/> guarda apenas <b>a chave</b> da conversa; o
-/// conteudo mora onde o projeto puder consulta-lo — tipicamente uma coluna <c>jsonb</c>.
-/// </para>
-/// <para>
-/// <b>A invariante que o teste cobra:</b> o provider e <b>uma instancia compartilhada por
-/// todas as sessoes</b>. Por isso este tipo <b>nao tem campo de estado por conversa</b> — o
-/// unico estado por sessao vive em <see cref="ProviderSessionState{TState}"/>, dentro da
-/// propria <see cref="AgentSession"/>. Um campo de instancia guardando "a conversa atual"
-/// e como o historico de um usuario aparece na tela de outro, e a falha nao aparece em teste
-/// de uma sessao so: aparece em producao, sob concorrencia, como vazamento de dado alheio.
-/// </para>
-/// <para>
-/// <b>De onde vem a chave da conversa</b>, nesta ordem:
-/// <list type="number">
-/// <item>o que o projeto amarrou com <see cref="BindConversation"/> — o caso do CRM, em que
-/// a conversa ja existe como registro antes de o agente entrar;</item>
-/// <item>o <c>ConversationId</c> da sessao, quando o proprio provider de modelo gerencia a
-/// conversa (<see cref="ChatClientAgentSession"/>);</item>
-/// <item>um id novo, <see cref="Guid.CreateVersion7"/> — ordenavel no tempo, ao contrario de
-/// <c>Guid.NewGuid</c>, que fragmenta indice de banco.</item>
-/// </list>
-/// </para>
-/// </remarks>
+// Uma instancia atende todas as sessoes: estado por conversa so em ProviderSessionState, nunca em campo.
 public sealed class ConversationStore : ChatHistoryProvider
 {
-    /// <summary>
-    /// Chave sob a qual a identidade da conversa e guardada no estado da sessao. Fixa e
-    /// publica porque ela viaja na serializacao da sessao: mudar esta string quebra a
-    /// retomada de toda conversa ja persistida.
-    /// </summary>
+    // Viaja na serializacao da sessao: mudar a string quebra a retomada das conversas ja persistidas.
     public const string ConversationIdStateKey = "morph.conversation.id";
 
     private readonly IConversationStore _store;
     private readonly ProviderSessionState<string> _conversationId;
 
-    /// <summary>Monta o provider sobre um acervo.</summary>
-    /// <param name="store">Onde o historico e lido e gravado. Nunca nulo.</param>
     public ConversationStore(IConversationStore store)
     {
         ArgumentNullException.ThrowIfNull(store);
@@ -59,23 +20,8 @@ public sealed class ConversationStore : ChatHistoryProvider
         _conversationId = new ProviderSessionState<string>(NewConversationId, ConversationIdStateKey);
     }
 
-    /// <inheritdoc />
-    /// <remarks>
-    /// Declara a chave que este provider ocupa no estado da sessao — e o que permite ao MAF
-    /// serializar e retomar uma sessao sem adivinhar o que e de quem.
-    /// </remarks>
     public override IReadOnlyList<string> StateKeys => [ConversationIdStateKey];
 
-    /// <summary>
-    /// Amarra a sessao a uma conversa que <b>ja existe</b> no acervo do projeto. E o caminho
-    /// do CRM: a conversa nasce como registro de negocio, e o agente entra nela.
-    /// </summary>
-    /// <remarks>
-    /// Chamar isto depois de a sessao ja ter carregado historico troca a conversa sob os pes
-    /// da sessao. Amarre logo apos <c>CreateSessionAsync</c>.
-    /// </remarks>
-    /// <param name="session">A sessao.</param>
-    /// <param name="conversationId">A chave da conversa no acervo.</param>
     public void BindConversation(AgentSession session, string conversationId)
     {
         ArgumentNullException.ThrowIfNull(session);
@@ -84,10 +30,6 @@ public sealed class ConversationStore : ChatHistoryProvider
         _conversationId.SaveState(session, conversationId);
     }
 
-    /// <summary>
-    /// A chave da conversa desta sessao, criando-a se ainda nao houver. Le e escreve
-    /// <b>na sessao</b>, jamais num campo deste objeto.
-    /// </summary>
     public string GetConversationId(AgentSession session)
     {
         ArgumentNullException.ThrowIfNull(session);
@@ -95,11 +37,7 @@ public sealed class ConversationStore : ChatHistoryProvider
         return _conversationId.GetOrInitializeState(session);
     }
 
-    /// <inheritdoc />
-    /// <remarks>
-    /// Devolve o historico guardado; as mensagens desta volta sao acrescentadas pelo agente
-    /// depois. Repetir aqui as mensagens do pedido duplicaria o turno corrente no prompt.
-    /// </remarks>
+    // O MAF acrescenta as mensagens desta volta depois; devolve-las aqui duplicaria o turno no prompt.
     protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
         InvokingContext context,
         CancellationToken cancellationToken = default)
@@ -111,19 +49,6 @@ public sealed class ConversationStore : ChatHistoryProvider
             .ConfigureAwait(false);
     }
 
-    /// <inheritdoc />
-    /// <remarks>
-    /// <para>
-    /// Grava o pedido e a resposta <b>desta</b> volta, nessa ordem — e so eles. Regravar o
-    /// historico inteiro a cada volta faria a conversa crescer em progressao geometrica.
-    /// </para>
-    /// <para>
-    /// <b>Volta que falhou nao e gravada.</b> Com <c>InvokeException</c> preenchida nao ha
-    /// resposta; persistir o pedido sozinho deixaria a conversa terminando numa pergunta que
-    /// o modelo nunca respondeu, e a proxima volta a mandaria de novo — o usuario veria a si
-    /// mesmo repetido.
-    /// </para>
-    /// </remarks>
     protected override async ValueTask StoreChatHistoryAsync(
         InvokedContext context,
         CancellationToken cancellationToken = default)
@@ -135,9 +60,6 @@ public sealed class ConversationStore : ChatHistoryProvider
             return;
         }
 
-        // Os dois lados sao anulaveis no contrato do MAF (a resposta some quando a volta
-        // falhou, e o pedido pode vir vazio numa continuacao). Tratados como ausencia, nunca
-        // desreferenciados.
         List<ChatMessage> round =
         [
             .. context.RequestMessages ?? [],
@@ -154,13 +76,6 @@ public sealed class ConversationStore : ChatHistoryProvider
             .ConfigureAwait(false);
     }
 
-    /// <summary>
-    /// O MAF declara <c>InvokingContext.Session</c> como anulavel, e uma invocacao sem
-    /// sessao nao tem onde guardar a identidade da conversa. As duas saidas silenciosas sao
-    /// piores que a recusa: inventar um id grava uma linha orfa que ninguem consegue ler de
-    /// novo, e usar uma chave fixa junta conversas de tenants diferentes no mesmo balde —
-    /// que e o vazamento que este provider existe para impedir.
-    /// </summary>
     private static AgentSession RequireSession(AgentSession? session)
         => session ?? throw new InvalidOperationException(
             "ConversationStore foi invocado sem AgentSession. Sem sessao nao ha identidade de " +

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/IConversationStore.cs

@@ -2,51 +2,11 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Conversation;
 
-/// <summary>
-/// Onde o historico de conversa fica guardado. <b>A costura entre o kit e o banco do
-/// projeto</b> — e o unico ponto do <see cref="ConversationStore"/> que um projeto precisa
-/// implementar para trocar memoria por tabela.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>A decisao da casa que este tipo torna compilavel:</b> a conversa vive no armazenamento
-/// <b>do projeto</b>, nao dentro da <c>AgentSession</c>. Num CRM multi-tenant a conversa e
-/// um registro de negocio — ela precisa sobreviver ao restart do processo, ser lida por
-/// relatorio, ser filtrada por tenant e ser apagada a pedido do titular. Nada disso e
-/// possivel quando o historico so existe na memoria de uma sessao.
-/// </para>
-/// <para>
-/// <b>O kit nao conhece banco.</b> Esta interface e deliberadamente pequena e sem tipo de
-/// infraestrutura na assinatura: nenhum <c>DbContext</c>, nenhuma conexao, nenhum
-/// <c>jsonb</c>. A implementacao de producao vive no projeto (handler falando com o
-/// <c>ApplicationDbContext</c> direto, sem camada de service e sem repository generico);
-/// a implementacao de teste e <see cref="InMemoryConversationStore"/>.
-/// </para>
-/// <para>
-/// <b>Contrato de identidade:</b> <c>conversationId</c> e a chave do acervo, opaca para o
-/// kit. Num CRM ela costuma ser o id da linha de conversa — e por isso
-/// <see cref="ConversationStore.BindConversation"/> existe: e como o projeto amarra uma
-/// sessao a uma conversa que ja existe, em vez de deixar o kit inventar um id.
-/// </para>
-/// <para>
-/// <b>Contrato de concorrencia:</b> uma unica instancia atende todas as sessoes ao mesmo
-/// tempo. A implementacao precisa ser segura para uso concorrente e, acima de tudo,
-/// <b>nunca deixar mensagem de uma conversa aparecer em outra</b> — a chave e o unico
-/// isolamento que existe aqui.
-/// </para>
-/// </remarks>
+// Uma instancia atende todas as sessoes ao mesmo tempo: a implementacao precisa ser segura sob concorrencia.
 public interface IConversationStore
 {
-    /// <summary>
-    /// O historico da conversa, na ordem cronologica. Conversa inexistente devolve lista
-    /// <b>vazia</b>, nunca nulo e nunca excecao: uma primeira volta e o caso normal.
-    /// </summary>
     ValueTask<IReadOnlyList<ChatMessage>> LoadAsync(string conversationId, CancellationToken cancellationToken);
 
-    /// <summary>
-    /// Acrescenta as mensagens de uma volta ao fim da conversa. Chamado uma vez por volta,
-    /// com o pedido e a resposta daquela volta — nunca com o historico inteiro.
-    /// </summary>
     ValueTask AppendAsync(
         string conversationId,
         IReadOnlyList<ChatMessage> messages,

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/InMemoryConversationStore.cs

@@ -3,33 +3,13 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Conversation;
 
-/// <summary>
-/// <see cref="IConversationStore"/> em memoria. <b>Para teste e para prototipo</b> — nao
-/// para producao: o historico morre com o processo, e um CRM que perde a conversa no deploy
-/// nao tem conversa.
-/// </summary>
-/// <remarks>
-/// <para>
-/// Existe para que a suite do kit prove o <see cref="ConversationStore"/> <b>sem banco</b>,
-/// e para que um projeto tenha um exemplar de referencia do contrato antes de escrever a
-/// versao com <c>jsonb</c>.
-/// </para>
-/// <para>
-/// <b>Seguro sob concorrencia por construcao</b>, e nao por acidente: uma
-/// <see cref="ConcurrentDictionary{TKey, TValue}"/> por conversa, e a lista de cada conversa
-/// sempre mutada sob o lock daquela conversa. Sem isso, o teste de duas sessoes concorrentes
-/// mediria a falta de trava aqui em vez do isolamento do provider.
-/// </para>
-/// </remarks>
 public sealed class InMemoryConversationStore : IConversationStore
 {
     private readonly ConcurrentDictionary<string, List<ChatMessage>> _conversations =
         new(StringComparer.Ordinal);
 
-    /// <summary>As conversas que existem no acervo, para inspecao em teste.</summary>
     public IReadOnlyCollection<string> ConversationIds => _conversations.Keys.ToArray();
 
-    /// <inheritdoc />
     public ValueTask<IReadOnlyList<ChatMessage>> LoadAsync(
         string conversationId,
         CancellationToken cancellationToken)
@@ -48,7 +28,6 @@ public sealed class InMemoryConversationStore : IConversationStore
         }
     }
 
-    /// <inheritdoc />
     public ValueTask AppendAsync(
         string conversationId,
         IReadOnlyList<ChatMessage> messages,

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

@@ -2,39 +2,17 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>
-/// Conta quantas vezes o cliente interno foi realmente invocado, e repassa tudo o mais
-/// intacto.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que existe.</b> Nos modos que TEM cliente real (<see cref="EvalMode.Refresh"/> e
-/// <see cref="EvalMode.Online"/>) nao ha <see cref="OfflineChatClient"/> para contar, e sem
-/// contador o sumario nao consegue dizer se a arvore de cache mudou. "A cache esta fria" e
-/// uma afirmacao com consequencia (a arvore precisa ser commitada), e afirmacao com
-/// consequencia se mede.
-/// </para>
-/// <para>
-/// <b><see cref="GetService"/> repassa VERBATIM</b>, e isso e load-bearing: e por ele que o
-/// <c>ChatClientMetadata</c> — com o <c>ProviderName</c> e o <c>DefaultModelId</c> que
-/// entram na CHAVE de cache — chega a camada de cache. Um wrapper que respondesse por conta
-/// propria aqui gravaria a arvore sob uma identidade diferente da que a leitura offline
-/// replica, e todo cenario daria miss.
-/// </para>
-/// </remarks>
 public sealed class CountingChatClient(IChatClient inner) : IChatClient
 {
     private readonly IChatClient _inner = inner ?? throw new ArgumentNullException(nameof(inner));
     private readonly Lock _gate = new();
     private int _calls;
 
-    /// <summary>Quantas chamadas atravessaram ate o cliente real.</summary>
     public int Calls
     {
         get { lock (_gate) { return _calls; } }
     }
 
-    /// <inheritdoc />
     public Task<ChatResponse> GetResponseAsync(
         IEnumerable<ChatMessage> messages,
         ChatOptions? options = null,
@@ -44,7 +22,6 @@ public sealed class CountingChatClient(IChatClient inner) : IChatClient
         return _inner.GetResponseAsync(messages, options, cancellationToken);
     }
 
-    /// <inheritdoc />
     public IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
         IEnumerable<ChatMessage> messages,
         ChatOptions? options = null,
@@ -54,11 +31,10 @@ public sealed class CountingChatClient(IChatClient inner) : IChatClient
         return _inner.GetStreamingResponseAsync(messages, options, cancellationToken);
     }
 
-    /// <inheritdoc />
+    // Repassa verbatim: o ChatClientMetadata daqui entra na chave de cache.
     public object? GetService(Type serviceType, object? serviceKey = null)
         => _inner.GetService(serviceType, serviceKey);
 
-    /// <inheritdoc />
     public void Dispose() => _inner.Dispose();
 
     private void Count()

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

@@ -6,79 +6,31 @@ 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>
+    // Sem \b: a fronteira de palavra do .NET nao trata acento como letra em toda cultura.
     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)),
@@ -86,26 +38,17 @@ public sealed record EvalAssertion : IEvaluator
         ("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>
+    // Unico por cenario: a biblioteca indexa metricas por nome e a homonima sobrescreve em silencio.
     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);
@@ -135,12 +78,9 @@ public sealed record EvalAssertion : IEvaluator
             _ => 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,
@@ -156,7 +96,6 @@ public sealed record EvalAssertion : IEvaluator
         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();

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

@@ -1,36 +1,9 @@
 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))
     {
@@ -39,13 +12,10 @@ public sealed class EvalCacheMissException : Exception
         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)

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

@@ -1,78 +1,27 @@
 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>
+    // Sem default: o da biblioteca (14 dias) apaga a entrada vencida durante a leitura da arvore commitada.
     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; }
 }