@polymorphism-tech/morph-spec 8.38.0 → 8.41.0

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/GoogleImageProvider.cs

@@ -2,24 +2,7 @@ using Google.GenAI.Types;
 
 namespace Morph.AiKit.Media.Providers;
 
-/// <summary>
-/// Adaptador de imagem do Google (familia Nano Banana). <b><c>internal</c></b> — ver
-/// <see cref="IMediaProvider"/>.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Nao ha adaptador MEAI oficial para o Google</b> (medido em 2026-09-08: o unico
-/// <c>AsIImageGenerator()</c> publicado e o de OpenAI/Azure OpenAI). O caminho e
-/// <c>Google.GenAI</c> direto — <c>Models.GenerateContentAsync</c> com
-/// <c>ResponseModalities</c> incluindo <c>"IMAGE"</c>, lendo os bytes de
-/// <c>Candidates[0].Content.Parts[..].InlineData</c>.
-/// </para>
-/// <para>
-/// <c>GenerateImagesAsync</c> do SDK <b>nao serve</b>: ela e a API do Imagen, cuja familia
-/// <c>imagen-4.0-*</c> esta na tabela de deprecacoes de
-/// <c>ai-agents/modalities-image-gen.md</c>.
-/// </para>
-/// </remarks>
+// GenerateImagesAsync e a API do Imagen (familia deprecada); Nano Banana vai por GenerateContentAsync.
 internal sealed class GoogleImageProvider : IMediaProvider
 {
     private readonly IMediaClientFactory _clients;
@@ -30,13 +13,10 @@ internal sealed class GoogleImageProvider : IMediaProvider
         _clients = clients;
     }
 
-    /// <inheritdoc />
     public string Provider => "google";
 
-    /// <inheritdoc />
     public bool Supports(MediaKind kind) => kind == MediaKind.Image;
 
-    /// <inheritdoc />
     public async Task<MediaResult<MediaArtifact>> ProduceAsync(
         MediaRequest request,
         MediaAliasBinding binding,
@@ -55,9 +35,7 @@ internal sealed class GoogleImageProvider : IMediaProvider
 
         var parts = new List<Part> { new() { Text = request.Prompt } };
 
-        // Cada referencia entra como InlineData, na ORDEM em que o prompt as indexa
-        // ("image 1 = o sofa"). Referencia nao indexada e referencia cujo uso o modelo
-        // escolhe sozinho.
+        // A ordem das referencias e a que o prompt indexa ("image 1 = o sofa").
         foreach (var reference in request.References)
         {
             parts.Add(new Part
@@ -91,8 +69,6 @@ internal sealed class GoogleImageProvider : IMediaProvider
 
         if (blob is null)
         {
-            // Sem bytes e sem excecao: o caso tipico e filtro de conteudo. Terminal, e nao
-            // um erro tecnico que um retry resolveria.
             return MediaResult<MediaArtifact>.Fail(
                 MediaErrorCode.PolicyBlocked,
                 $"alias '{binding.Alias}': a resposta nao trouxe imagem. O caso tipico e filtro de " +
@@ -105,8 +81,7 @@ internal sealed class GoogleImageProvider : IMediaProvider
             blob.Data,
             RevisedPrompt: null,
             ResponseId: response.ResponseId,
-            // SynthID vem embutido em toda imagem Gemini, e os bytes vao para o blob como
-            // chegaram: nenhum re-encode entre a resposta e o storage.
+            // SynthID vem embutido e os bytes nao sao re-encodados ate o storage.
             C2paPreserved: true));
     }
 }

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/OpenAIImageProvider.cs

@@ -3,32 +3,8 @@ using OpenAI.Images;
 
 namespace Morph.AiKit.Media.Providers;
 
-/// <summary>
-/// Adaptador de imagem da OpenAI. <b><c>internal</c></b> — ver <see cref="IMediaProvider"/>.
-/// </summary>
-/// <remarks>
-/// <para>
-/// A chamada passa pela abstracao <see cref="IImageGenerator"/> de
-/// <c>Microsoft.Extensions.AI</c>, e nao pelo <c>ImageClient</c> cru, para que o pipeline
-/// nao fique acoplado ao SDK de um provider. A ponte oficial
-/// (<c>Microsoft.Extensions.AI.OpenAI.AsIImageGenerator()</c>) <b>nao esta no pin deste
-/// kit</b>, entao o adaptador <see cref="OpenAIImageGenerator"/> vive aqui, escrito a mao
-/// sobre o <c>ImageClient</c>. Trocar por <c>AsIImageGenerator()</c> e uma linha, no dia em
-/// que o pacote entrar em <c>framework/ai-pin.json</c>.
-/// </para>
-/// <para>
-/// <b>Medido contra o pin em 2026-09-08, nao suposto:</b>
-/// <c>Microsoft.Extensions.AI.IImageGenerator</c> carrega <c>[Experimental("MEAI001")]</c>
-/// e herda <c>IDisposable</c>; <c>ImageGenerationRequest</c> tem <c>Prompt</c> e
-/// <c>OriginalImages</c> (<c>IEnumerable&lt;AIContent&gt;</c>), e tambem e experimental;
-/// <c>ImageGenerationOptions</c> <b>nao</b> tem propriedade tipada para
-/// <c>quality</c>/<c>background</c>/<c>input_fidelity</c> — por isso a qualidade viaja em
-/// <c>AdditionalProperties</c> e e este adaptador que a traduz para o SDK.
-/// </para>
-/// </remarks>
 internal sealed class OpenAIImageProvider : IMediaProvider
 {
-    /// <summary>A chave sob a qual a qualidade viaja em <c>AdditionalProperties</c>.</summary>
     internal const string QualityKey = "quality";
 
     private readonly IMediaClientFactory _clients;
@@ -39,13 +15,10 @@ internal sealed class OpenAIImageProvider : IMediaProvider
         _clients = clients;
     }
 
-    /// <inheritdoc />
     public string Provider => "openai";
 
-    /// <inheritdoc />
     public bool Supports(MediaKind kind) => kind == MediaKind.Image;
 
-    /// <inheritdoc />
     public async Task<MediaResult<MediaArtifact>> ProduceAsync(
         MediaRequest request,
         MediaAliasBinding binding,
@@ -69,9 +42,6 @@ internal sealed class OpenAIImageProvider : IMediaProvider
 
         if (request.References.Count > 0)
         {
-            // OriginalImages e o gancho de EDICAO: preserva o produto real em vez de
-            // recria-lo. Gerar do zero quando a foto existe inventa material, medida ou cor
-            // que o produto nao tem — o claim visual falso que o AI Act art. 50 mira.
             generationRequest.OriginalImages =
                 [.. request.References.Select(r => new DataContent(r.Bytes, r.MediaType))];
         }
@@ -90,8 +60,7 @@ internal sealed class OpenAIImageProvider : IMediaProvider
 
         if (request.Options.Quality is { } quality)
         {
-            // Nao ha propriedade tipada na 10.9.0 — medido. Vai por AdditionalProperties, e
-            // o adaptador acima e quem traduz para o SDK.
+            // MEAI 10.9.0 nao tem propriedade tipada para qualidade.
             options.AdditionalProperties = new AdditionalPropertiesDictionary
             {
                 [QualityKey] = quality.ToString(),
@@ -119,16 +88,13 @@ internal sealed class OpenAIImageProvider : IMediaProvider
                 data.Data,
                 RevisedPrompt: (response.RawRepresentation as GeneratedImage)?.RevisedPrompt,
                 ResponseId: null,
-                // Os bytes chegam como o provider os produziu: nenhum re-encode entre a
-                // resposta e o blob. E o que mantem a credencial C2PA viva.
+                // Nenhum re-encode entre a resposta e o blob: e o que mantem a credencial C2PA viva.
                 C2paPreserved: true));
         }
 #pragma warning restore MEAI001
         catch (System.ClientModel.ClientResultException ex)
         {
-            // Bloqueio de moderacao e resposta DEFINITIVA, nunca erro tecnico: retentar
-            // gasta para receber o mesmo "nao". A distincao mora aqui, no unico ponto que
-            // ve o codigo HTTP.
+            // A OpenAI devolve bloqueio de moderacao como HTTP 400: terminal, nunca retry.
             return ex.Status == 400
                 ? MediaResult<MediaArtifact>.Fail(
                     MediaErrorCode.PolicyBlocked,
@@ -140,20 +106,8 @@ internal sealed class OpenAIImageProvider : IMediaProvider
     }
 }
 
-/// <summary>
-/// <see cref="IImageGenerator"/> escrito a mao sobre o <c>ImageClient</c> do SDK da OpenAI.
-/// </summary>
-/// <remarks>
-/// Existe porque <c>Microsoft.Extensions.AI.OpenAI</c> — que traz
-/// <c>AsIImageGenerator()</c> — nao esta em <c>framework/ai-pin.json</c>, e acrescentar
-/// pacote e mexer no pin. O contrato imitado e o mesmo: <c>OriginalImages</c> vazio vira
-/// <c>GenerateImageAsync</c>; com referencia, vira <c>GenerateImageEditAsync</c>, que e o
-/// caminho que PRESERVA o produto real.
-/// </remarks>
-// OPENAI001 entra junto, e nao por preguica: GeneratedImageQuality.{Low,Medium,High}Quality
-// e ImageEditOptions.Quality carregam o diagnostico de "evaluation only" no OpenAI 2.13.0 —
-// medido pelo compilador, nao suposto. Suprimir os dois com o motivo escrito e o item 3 do
-// checklist de ai-agents/modalities-image-gen.md.
+// Escrito a mao porque AsIImageGenerator() (Microsoft.Extensions.AI.OpenAI) nao esta no pin.
+// OPENAI001: GeneratedImageQuality e ImageEditOptions.Quality sao "evaluation only" no OpenAI 2.13.0.
 #pragma warning disable MEAI001, OPENAI001
 internal sealed class OpenAIImageGenerator : IImageGenerator
 {
@@ -211,9 +165,7 @@ internal sealed class OpenAIImageGenerator : IImageGenerator
 
     public void Dispose()
     {
-        // O ImageClient nao e IDisposable e o seu tempo de vida e do projeto: a fabrica de
-        // clientes cria, o projeto descarta. Descartar aqui seria uma segunda dona do mesmo
-        // recurso — foi assim que um cliente vazou de um teste, uma vez.
+        // O ImageClient pertence a fabrica de clientes; descartar aqui seria uma segunda dona.
     }
 
     private static OpenAI.Images.ImageGenerationOptions BuildGenerationOptions(
@@ -221,8 +173,6 @@ internal sealed class OpenAIImageGenerator : IImageGenerator
     {
         var sdk = new OpenAI.Images.ImageGenerationOptions
         {
-            // Bytes, sempre. Uma URL de provider expira, e um caminho quebrado depois e um
-            // arquivo pelo qual se pagou e que nao existe mais.
             ResponseFormat = GeneratedImageFormat.Bytes,
         };
 
@@ -256,10 +206,6 @@ internal sealed class OpenAIImageGenerator : IImageGenerator
         return sdk;
     }
 
-    /// <summary>
-    /// Traduz a qualidade que viajou em <c>AdditionalProperties</c>. Chave ausente devolve
-    /// nulo — e nulo significa "nao envia ao provider", nunca "manda o default do kit".
-    /// </summary>
     private static GeneratedImageQuality? QualityOf(Microsoft.Extensions.AI.ImageGenerationOptions? options)
     {
         if (options?.AdditionalProperties is not { } extra
@@ -285,4 +231,4 @@ internal sealed class OpenAIImageGenerator : IImageGenerator
         _ => "reference.png",
     };
 }
-#pragma warning restore MEAI001
+#pragma warning restore MEAI001, OPENAI001

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/VeoVideoProvider.cs

@@ -2,40 +2,11 @@ using Google.GenAI.Types;
 
 namespace Morph.AiKit.Media.Providers;
 
-/// <summary>
-/// Adaptador de video do Veo. <b><c>internal</c></b> — ver <see cref="IMediaProvider"/>.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>E o unico caminho de video com SDK .NET oficial</b> depois do desligamento da Sora
-/// (data em <c>ai-agents/media-video.md</c>, secao Deprecacoes). Seedance, Kling e Runway
-/// exigem <c>HttpClient</c> tipado com DTOs proprios, e por isso nao tem adaptador aqui.
-/// </para>
-/// <para>
-/// <b>Assinatura medida contra Google.GenAI 1.21.0, nao lida em blog:</b>
-/// <c>Models.GenerateVideosAsync(string model, GenerateVideosSource source,
-/// GenerateVideosConfig config, CancellationToken)</c> devolve
-/// <c>GenerateVideosOperation</c> — o prompt vai DENTRO de <c>GenerateVideosSource</c>, e
-/// nao como parametro solto. O polling e
-/// <c>Operations.GetAsync(operation, config, ct)</c>, e o veredito e
-/// <c>operation.Done</c>.
-/// </para>
-/// <para>
-/// <b>Os bytes sao baixados AQUI.</b> O Veo retem o arquivo por 2 dias; devolver a URL e
-/// entregar um link que morre. Quando a resposta so traz <c>Uri</c>, este adaptador recusa
-/// com motivo em vez de guardar a URL fingindo que e permanente.
-/// </para>
-/// </remarks>
 internal sealed class VeoVideoProvider : IMediaProvider
 {
-    /// <summary>Intervalo entre voltas do polling. ~10 s e o intervalo que a doc do Veo usa.</summary>
     internal static readonly TimeSpan PollInterval = TimeSpan.FromSeconds(10);
 
-    /// <summary>
-    /// Teto de voltas. Existe porque <c>Done</c> que nunca vira <c>true</c> e um caso real,
-    /// e um laco sem saida e indistinguivel de um worker travado. 60 voltas cobrem os 6 min
-    /// documentados como pior caso, com folga.
-    /// </summary>
+    // Cobre os 6 min documentados como pior caso do Veo; Done pode nunca virar true.
     internal const int MaxPolls = 60;
 
     private readonly IMediaClientFactory _clients;
@@ -48,13 +19,10 @@ internal sealed class VeoVideoProvider : IMediaProvider
         _delay = delay ?? Task.Delay;
     }
 
-    /// <inheritdoc />
     public string Provider => "google";
 
-    /// <inheritdoc />
     public bool Supports(MediaKind kind) => kind == MediaKind.Video;
 
-    /// <inheritdoc />
     public async Task<MediaResult<MediaArtifact>> ProduceAsync(
         MediaRequest request,
         MediaAliasBinding binding,
@@ -80,8 +48,7 @@ internal sealed class VeoVideoProvider : IMediaProvider
 
         if (request.References.Count > 0)
         {
-            // O Veo exige 8 s quando ha imagens de referencia. Pedir 4 s COM referencia e
-            // requisicao invalida, e descobrir isso em producao custa uma rodada de suporte.
+            // O Veo exige 8 s quando ha imagens de referencia.
             config.ReferenceImages =
             [
                 .. request.References.Select(r => new VideoGenerationReferenceImage
@@ -127,8 +94,6 @@ internal sealed class VeoVideoProvider : IMediaProvider
 
         if (response?.RaiMediaFilteredCount is > 0)
         {
-            // Bloqueio de moderacao. No Veo ele NAO cobra — e nao vira retry, porque
-            // retentar recebe o mesmo "nao".
             return MediaResult<MediaArtifact>.Fail(
                 MediaErrorCode.PolicyBlocked,
                 $"alias '{binding.Alias}': {response.RaiMediaFilteredCount} saida(s) bloqueada(s) por politica: " +

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Middleware/IUsageCostSink.cs

@@ -1,29 +1,7 @@
 namespace Morph.AiKit.Middleware;
 
-/// <summary>
-/// Para onde vai o custo de cada volta ao modelo. <b>A costura de saida do
-/// <see cref="UsageCostMiddleware"/></b>: o kit calcula, o projeto decide onde guardar
-/// (tabela, metrica, log estruturado, fila).
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que uma interface de um metodo so e nao um evento nem um logger:</b> custo e
-/// dado de negocio, nao diagnostico. Um projeto multi-tenant precisa somar por conta e por
-/// mes; um <c>ILogger</c> nao devolve soma. A interface e minima de proposito — quem quiser
-/// um logger implementa um sink de duas linhas.
-/// </para>
-/// <para>
-/// <b>Contrato de execucao:</b> <see cref="Record"/> e chamado no caminho da resposta,
-/// <b>sincronamente</b>, uma vez por volta ao modelo. Uma implementacao que faca I/O
-/// bloqueante aqui paga esse custo na latencia de cada resposta — enfileire e persista fora
-/// do caminho quente. E ela pode ser chamada de varias threads ao mesmo tempo (um mesmo
-/// pipeline atende varias conversas): a implementacao e responsavel pela propria seguranca
-/// sob concorrencia.
-/// </para>
-/// </remarks>
 public interface IUsageCostSink
 {
-    /// <summary>Publica o custo de uma volta ao modelo.</summary>
-    /// <param name="record">O registro ja calculado. Nunca nulo.</param>
+    // Chamado sincronamente no caminho da resposta e de varias threads: I/O aqui vira latencia.
     void Record(UsageCostRecord record);
 }

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Middleware/UsageCostMiddleware.cs

@@ -4,68 +4,12 @@ using Morph.AiKit.Providers;
 
 namespace Morph.AiKit.Middleware;
 
-/// <summary>
-/// Middleware de <see cref="IChatClient"/> que le o <c>Usage</c> da resposta, aplica a
-/// tarifa do alias e publica uma linha de custo em <see cref="IUsageCostSink"/>.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Onde ele entra no pipeline:</b> <b>ACIMA</b> da invocacao de funcoes, com a
-/// telemetria de chat abaixo dela (<c>usage-cost -&gt; function-invocation -&gt;
-/// OpenTelemetry -&gt; cliente do provider</c>). Na pratica: a
-/// <c>AgentFactory.BuildChatPipeline</c> registra o encaixe de custo <b>antes</b> de
-/// <c>UseFunctionInvocation</c>, e no <c>ChatClientBuilder</c> o primeiro registrado e o
-/// mais <b>externo</b>. A ordem nao e estetica, e o motivo e o
-/// <c>FunctionInvokingChatClient</c> (FICC): acima dele o middleware ve <b>uma</b> resposta
-/// cujo <c>Usage</c> ja vem com o total de todas as voltas de tool (medido: duas voltas de
-/// 10/4 e 30/6 chegam como <c>in=40, out=10</c>) e publica <b>uma</b> linha por chamada.
-/// Abaixo dele veria as respostas parciais — e leria o mesmo objeto <c>UsageDetails</c> que
-/// o proprio FICC <b>muta</b> para acumular, o que faria a mesma conta dar resultado
-/// diferente conforme a hora de ler. Isso e medido, nao argumentado, em
-/// <c>AgentFactoryTests.ThePipelineOrderIsUsageCostAboveFunctionInvocationAndTelemetryBelowIt</c>
-/// (sequencia <c>usage-cost:enter -&gt; telemetry:enter/exit x2 -&gt; usage-cost:exit</c>) e
-/// em <c>AgentFactoryTests.UsageCostAboveFunctionInvocationSeesTheUsageOfEveryToolRoundSummedOnce</c>.
-/// A montagem do pipeline e da <c>AgentFactory</c> (T10); daqui so depende a extensao
-/// <see cref="UsageCostChatClientBuilderExtensions.UseUsageCost"/>.
-/// </para>
-/// <para>
-/// <b>Nota de errata:</b> o <c>spec.md</c> sec. 3.1 desta feature prescrevia a seta
-/// literal <c>function-invocation -&gt; usage-cost -&gt; OpenTelemetry</c>, que se le ao
-/// contrario do que esta implementado aqui. A divergencia foi medida na T10 sec. 3.2 e esta
-/// registrada como <b>Errata E9</b> no proprio <c>spec.md</c> — o corpo do plano e
-/// append-only e continua com a seta antiga; a verdade e esta.
-/// </para>
-/// <para>
-/// <b>A conta e a do <see cref="ModelPricing.ComputeCostUsd"/>, nao uma segunda.</b> Este
-/// tipo nao contem aritmetica de tarifa: ele converte <c>Usage</c> em argumentos, chama a
-/// conta que ja existe e carimba o resultado. Reescrever a formula aqui daria dois numeros
-/// para o mesmo custo — que e literalmente a dor no nome desta epica (em ProspectPRO a
-/// conta esta repetida em cinco agentes).
-/// </para>
-/// <para>
-/// <b>Nunca lanca por causa de tarifa.</b> Alias sem tarifa e caminho previsto: sai
-/// <c>CostUsd = 0</c> com <see cref="UsageCostStatus.Waived"/> e o motivo escrito no
-/// record. Inventar tarifa e pior que nao ter. E resposta sem <c>Usage</c> sai como
-/// <see cref="UsageCostStatus.UsageMissing"/> — visivel, em vez de silenciosa.
-/// </para>
-/// </remarks>
 public sealed class UsageCostMiddleware : DelegatingChatClient
 {
     private readonly ModelAlias _alias;
     private readonly IUsageCostSink _sink;
     private readonly TimeProvider _timeProvider;
 
-    /// <summary>Monta o middleware sobre um cliente interno.</summary>
-    /// <param name="innerClient">O proximo elo do pipeline.</param>
-    /// <param name="alias">
-    /// O alias que atende este cliente — de onde vem a tarifa e o nome que vai no record.
-    /// </param>
-    /// <param name="sink">Para onde as linhas de custo vao.</param>
-    /// <param name="timeProvider">
-    /// Relogio. Nulo usa <see cref="TimeProvider.System"/>. Injetavel porque o standard
-    /// <c>backend-dotnet-testing</c> proibe <c>DateTimeOffset.UtcNow</c> direto num tipo
-    /// testavel — sem isso, o instante do record e intestavel.
-    /// </param>
     public UsageCostMiddleware(
         IChatClient innerClient,
         ModelAlias alias,
@@ -81,7 +25,6 @@ public sealed class UsageCostMiddleware : DelegatingChatClient
         _timeProvider = timeProvider ?? TimeProvider.System;
     }
 
-    /// <inheritdoc />
     public override async Task<ChatResponse> GetResponseAsync(
         IEnumerable<ChatMessage> messages,
         ChatOptions? options = null,
@@ -95,13 +38,7 @@ public sealed class UsageCostMiddleware : DelegatingChatClient
         return response;
     }
 
-    /// <inheritdoc />
-    /// <remarks>
-    /// No streaming o <c>Usage</c> chega como <see cref="UsageContent"/> avulso, tipicamente
-    /// no ultimo update — e pode chegar em mais de um pedaco. Os pedacos sao somados e a
-    /// linha de custo sai <b>uma unica vez</b>, ao fim da enumeracao: emitir por update daria
-    /// N linhas para uma volta so.
-    /// </remarks>
+    // No streaming o Usage pode chegar em mais de um UsageContent: soma e publica uma linha so, ao fim.
     public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
         IEnumerable<ChatMessage> messages,
         ChatOptions? options = null,
@@ -132,8 +69,6 @@ public sealed class UsageCostMiddleware : DelegatingChatClient
 
         if (usage is null || (usage.InputTokenCount is null && usage.OutputTokenCount is null))
         {
-            // Sem relato de uso nao ha o que tarifar. A linha sai assim mesmo, marcada: um
-            // custo que ninguem consegue medir precisa aparecer, nao sumir.
             _sink.Record(new UsageCostRecord(_alias.Name, 0, 0, null, 0m, at)
             {
                 Status = UsageCostStatus.UsageMissing,
@@ -147,8 +82,6 @@ public sealed class UsageCostMiddleware : DelegatingChatClient
 
         if (_alias.Pricing is not { } pricing)
         {
-            // Caminho previsto, nunca excecao: o alias declarou por escrito que nao tem
-            // tarifa (o registry recusa a carga de um alias sem tarifa E sem dispensa).
             _sink.Record(new UsageCostRecord(_alias.Name, input, output, cached, 0m, at)
             {
                 Status = UsageCostStatus.Waived,
@@ -157,9 +90,7 @@ public sealed class UsageCostMiddleware : DelegatingChatClient
             return;
         }
 
-        // Um provider que reporte 'cached' maior que 'input' esta se contradizendo; a conta
-        // do T8 recusa esse par. Aqui o dado inconsistente vira lacuna declarada, e nao uma
-        // excecao que derruba a resposta do usuario por causa de um contador.
+        // ComputeCostUsd recusa esse par; um contador incoerente do provider nao pode derrubar a resposta.
         if (cached > input)
         {
             _sink.Record(new UsageCostRecord(_alias.Name, input, output, cached, 0m, at)
@@ -182,19 +113,8 @@ public sealed class UsageCostMiddleware : DelegatingChatClient
     }
 }
 
-/// <summary>
-/// Registro do <see cref="UsageCostMiddleware"/> no pipeline de <see cref="IChatClient"/>.
-/// </summary>
 public static class UsageCostChatClientBuilderExtensions
 {
-    /// <summary>
-    /// Insere a contabilizacao de custo no pipeline, com a tarifa do alias dado.
-    /// </summary>
-    /// <param name="builder">O builder do pipeline.</param>
-    /// <param name="alias">Alias que atende este cliente.</param>
-    /// <param name="sink">Destino das linhas de custo.</param>
-    /// <param name="timeProvider">Relogio; nulo usa <see cref="TimeProvider.System"/>.</param>
-    /// <returns>O proprio builder, para encadear.</returns>
     public static ChatClientBuilder UseUsageCost(
         this ChatClientBuilder builder,
         ModelAlias alias,

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Middleware/UsageCostRecord.cs

@@ -2,74 +2,16 @@ using Morph.AiKit.Providers;
 
 namespace Morph.AiKit.Middleware;
 
-/// <summary>
-/// Como o custo de uma volta ao modelo ficou conhecido. Existe para que
-/// <see cref="UsageCostRecord.CostUsd"/> possa ser um <see cref="decimal"/> nao-anulavel
-/// <b>sem que zero passe a significar tres coisas diferentes</b>.
-/// </summary>
-/// <remarks>
-/// A dor que esta feature nomeia e <c>cost_usd</c> saindo nulo. Trocar o nulo por um zero
-/// mudo seria trocar um defeito por outro pior — zero soma, nulo nao. Aqui o valor e sempre
-/// um numero e o status diz se aquele numero e uma medicao, uma decisao ou uma lacuna.
-/// </remarks>
 public enum UsageCostStatus
 {
-    /// <summary>
-    /// Tarifa do alias aplicada sobre uso reportado pelo provider. O unico status em que
-    /// <see cref="UsageCostRecord.CostUsd"/> e uma <b>medicao</b> — e o unico que pode
-    /// entrar numa soma de fatura sem ressalva.
-    /// </summary>
     Computed = 0,
 
-    /// <summary>
-    /// O alias nao tem tarifa e <b>tem dispensa escrita</b>
-    /// (<c>ModelAlias.PricingWaiver</c>). Custo zero por decisao registrada — modelo local,
-    /// por exemplo, onde a conta e a maquina e nao o token. O motivo viaja em
-    /// <see cref="UsageCostRecord.PricingWaiver"/>: um zero aqui nunca e anonimo.
-    /// </summary>
     Waived = 1,
 
-    /// <summary>
-    /// O provider <b>nao reportou</b> <c>Usage</c> nesta volta. Os tokens sao desconhecidos,
-    /// logo o custo tambem e: o zero em <see cref="UsageCostRecord.CostUsd"/> e ausencia de
-    /// medicao, <b>nao</b> gratuidade. Some com <see cref="Computed"/> apenas ciente disso.
-    /// </summary>
+    // O zero de CostUsd aqui e ausencia de medicao, nao gratuidade.
     UsageMissing = 2,
 }
 
-/// <summary>
-/// O custo de uma volta ao modelo, ja calculado. <b>Uma linha por resposta</b>, pronta para
-/// virar registro de banco, metrica ou linha de fatura.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b><see cref="CostUsd"/> nunca e nulo — por construcao do tipo.</b> Esse e o ponto
-/// inteiro: a dor catalogada na issue e um <c>cost_usd</c> nulo atravessando tres camadas
-/// e aparecendo como buraco no relatorio. A ausencia de tarifa deixou de poder chegar ate
-/// aqui por esquecimento: o <c>ModelRegistry</c> (T8) <b>recusa a carga</b> de um alias que
-/// nao declare <c>pricing</c> nem <c>pricingWaiver</c>. Logo, quando este record sai com
-/// <see cref="UsageCostStatus.Waived"/>, existe necessariamente um motivo escrito em
-/// <see cref="PricingWaiver"/>.
-/// </para>
-/// <para>
-/// <b>A conta nao mora aqui.</b> Ela mora em <see cref="ModelPricing.ComputeCostUsd"/>
-/// (T8), e o <see cref="UsageCostMiddleware"/> apenas a chama. Uma segunda aritmetica do
-/// mesmo custo e o defeito que esta epica tem no nome: em ProspectPRO ela esta repetida
-/// literalmente em cinco agentes, e duas copias da mesma conta divergem — a divergencia
-/// aparece na fatura.
-/// </para>
-/// </remarks>
-/// <param name="Alias">O alias do <c>ModelRegistry</c> que atendeu a volta.</param>
-/// <param name="InputTokens">Tokens de entrada reportados. Zero quando nao houve relato.</param>
-/// <param name="OutputTokens">Tokens de saida reportados. Zero quando nao houve relato.</param>
-/// <param name="CachedInputTokens">
-/// Tokens de entrada servidos do cache do provider, ou nulo quando o provider nao reporta.
-/// E <b>subconjunto</b> de <paramref name="InputTokens"/>, nunca uma parcela a mais.
-/// </param>
-/// <param name="CostUsd">
-/// Custo em USD. Nunca nulo; leia <see cref="Status"/> antes de somar.
-/// </param>
-/// <param name="At">Instante da volta, vindo do <see cref="TimeProvider"/> injetado.</param>
 public sealed record UsageCostRecord(
     string Alias,
     long InputTokens,
@@ -78,18 +20,9 @@ public sealed record UsageCostRecord(
     decimal CostUsd,
     DateTimeOffset At)
 {
-    /// <summary>Como o custo ficou conhecido. Ver <see cref="UsageCostStatus"/>.</summary>
     public required UsageCostStatus Status { get; init; }
 
-    /// <summary>
-    /// O motivo escrito de o alias nao ter tarifa, copiado de
-    /// <c>ModelAlias.PricingWaiver</c>. Preenchido <b>somente</b> com
-    /// <see cref="UsageCostStatus.Waived"/>.
-    /// </summary>
     public string? PricingWaiver { get; init; }
 
-    /// <summary>
-    /// Se <see cref="CostUsd"/> e uma medicao — o unico caso em que somar e honesto.
-    /// </summary>
     public bool IsMeasuredCost => Status == UsageCostStatus.Computed;
 }

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Observability/MorphOpenTelemetryExtensions.cs

@@ -4,48 +4,8 @@ using Morph.AiKit.Agents;
 
 namespace Morph.AiKit.Observability;
 
-/// <summary>
-/// Liga as GenAI semantic conventions nos dois niveis do kit — agente e chat client — com
-/// <b>um guard contra span duplicado em cada um</b>.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>O que foi medido no pin (Microsoft.Agents.AI 1.20.0), e nao suposto:</b>
-/// </para>
-/// <list type="bullet">
-///   <item>
-///     Uma invocacao instrumentada produz <c>invoke_agent</c> (raiz) e <c>chat</c> (filho).
-///     Duas camadas de instrumentacao no MESMO nivel produzem o span daquele nivel duas
-///     vezes: dois <c>OpenTelemetryChatClient</c> dao dois <c>chat</c>; dois
-///     <c>OpenTelemetryAgent</c> dao dois <c>invoke_agent</c>.
-///   </item>
-///   <item>
-///     <c>GetService</c> atravessa a cadeia de delegates nos dois niveis — e por isso que
-///     "ja existe instrumentacao aqui embaixo?" e uma pergunta respondivel, e nao um
-///     palpite. E o predicado dos dois guards.
-///   </item>
-///   <item>
-///     O MAF 1.20.0 tem um guard proprio, mas ele so alcanca o pipeline que o
-///     <c>ChatClientAgent</c> monta sozinho. A <c>AgentFactory</c> monta o proprio
-///     (<c>UseProvidedChatClientAsIs = true</c>) para poder posicionar o custo e ajustar o
-///     tool calling — e nesse arranjo o slot do MAF nao existe. Medido: agente
-///     instrumentado + pipeline proprio sem estas extensoes = <b>zero</b> spans de chat.
-///     O guard daqui nao duplica o do MAF; ele cobre o pipeline que o MAF nao ve.
-///   </item>
-/// </list>
-/// </remarks>
 public static class MorphOpenTelemetryExtensions
 {
-    /// <summary>
-    /// Instrumenta o pipeline de chat. Aplicado pela <c>AgentFactory</c> ABAIXO do
-    /// <c>FunctionInvokingChatClient</c>, que e onde o MAF 1.20.0 documenta que a
-    /// instrumentacao tem de ficar para o span de chat fechar antes das tools.
-    /// </summary>
-    /// <remarks>
-    /// O guard vive na decisao de <see cref="ShouldInstrument"/>: com
-    /// <see cref="MorphTelemetryOptions.InstrumentChatClient"/> nulo (o default), um
-    /// pipeline que ja carrega um <see cref="OpenTelemetryChatClient"/> e devolvido intacto.
-    /// </remarks>
     public static ChatClientBuilder UseMorphTelemetry(this ChatClientBuilder builder, MorphTelemetryOptions options)
     {
         ArgumentNullException.ThrowIfNull(builder);
@@ -59,10 +19,6 @@ public static class MorphOpenTelemetryExtensions
             : inner);
     }
 
-    /// <summary>
-    /// Instrumenta o agente — o span <c>invoke_agent</c>, o mais externo, que cobre a
-    /// invocacao inteira. Um agente que ja e instrumentado e devolvido intacto.
-    /// </summary>
     public static AIAgentBuilder UseMorphTelemetry(this AIAgentBuilder builder, MorphTelemetryOptions options)
     {
         ArgumentNullException.ThrowIfNull(builder);
@@ -76,20 +32,6 @@ public static class MorphOpenTelemetryExtensions
             });
     }
 
-    /// <summary>
-    /// Preenche os dois encaixes de telemetria da <see cref="AgentFactoryOptions"/> de uma
-    /// vez, respeitando <see cref="AgentSpecOptions.EnableSensitiveTelemetry"/> quando a
-    /// spec opinou.
-    /// </summary>
-    /// <remarks>
-    /// A fabrica e dona da POSICAO de cada encaixe; esta extensao so diz o que ocupa cada
-    /// um. E por aqui que a T10 e a T12 se encontram sem uma referenciar a outra.
-    /// <para>
-    /// <c>EnableSensitiveTelemetry</c> nulo na spec significa "nao opinei" e mantem o valor
-    /// destas opcoes; <c>false</c> significa "decidi que nao" e vence. A diferenca entre os
-    /// dois e preservada de proposito desde a T7.
-    /// </para>
-    /// </remarks>
     public static AgentFactoryOptions WithMorphTelemetry(
         this AgentFactoryOptions factoryOptions,
         MorphTelemetryOptions options)
@@ -109,10 +51,7 @@ public static class MorphOpenTelemetryExtensions
             ? options with { EnableSensitiveData = sensitive }
             : options;
 
-    /// <summary>
-    /// <b>O guard.</b> Nulo = instrumenta so o que ainda nao esta instrumentado;
-    /// <c>true</c> = instrumenta sempre (e duplica, quando ja havia); <c>false</c> = nunca.
-    /// </summary>
+    // GetService atravessa a cadeia de delegates (MAF 1.20.0), entao detecta instrumentacao ja aplicada abaixo.
     private static bool ShouldInstrument(IChatClient inner, MorphTelemetryOptions options)
         => options.InstrumentChatClient
             ?? inner.GetService(typeof(OpenTelemetryChatClient)) is null;