@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

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

@@ -1,23 +1,5 @@
 namespace Morph.AiKit.Media;
 
-/// <summary>
-/// Tarifa de midia.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Nao e o <c>ModelPricing</c> do registry, e a diferenca e a UNIDADE.</b>
-/// <c>ModelPricing</c> cobra por 1M de tokens; imagem cobra por imagem e por qualidade, e
-/// video cobra por segundo de saida. Espremer as tres unidades na mesma tarifa produz custo
-/// errado em silencio — que e a pior forma de custo errado, porque nada grita.
-/// </para>
-/// <para>
-/// Os numeros NAO moram aqui. Eles moram nas tabelas datadas de
-/// <c>ai-agents/modalities-image-gen.md</c> (secao "Custo por chamada") e
-/// <c>ai-agents/media-video.md</c> (secao "Custo por segundo"), e sao carregados do
-/// <c>model-registry.v2.json</c> do projeto. Um preco chumbado em codigo envelhece sem que
-/// ninguem reveja o standard.
-/// </para>
-/// </remarks>
 public sealed record MediaPricing
 {
     private readonly decimal _low;
@@ -34,11 +16,8 @@ public sealed record MediaPricing
         _perSecond = perSecond;
     }
 
-    /// <summary>A que tipo de midia esta tarifa se aplica.</summary>
     public MediaKind Kind { get; }
 
-    /// <summary>Tarifa de imagem, em USD por imagem, por faixa de qualidade.</summary>
-    /// <exception cref="ArgumentOutOfRangeException">Tarifa negativa.</exception>
     public static MediaPricing PerImage(decimal low, decimal medium, decimal high)
     {
         ArgumentOutOfRangeException.ThrowIfNegative(low);
@@ -48,8 +27,6 @@ public sealed record MediaPricing
         return new MediaPricing(MediaKind.Image, low, medium, high, 0m);
     }
 
-    /// <summary>Tarifa de video, em USD por segundo de saida.</summary>
-    /// <exception cref="ArgumentOutOfRangeException">Tarifa negativa.</exception>
     public static MediaPricing PerSecond(decimal usdPerSecond)
     {
         ArgumentOutOfRangeException.ThrowIfNegative(usdPerSecond);
@@ -57,16 +34,6 @@ public sealed record MediaPricing
         return new MediaPricing(MediaKind.Video, 0m, 0m, 0m, usdPerSecond);
     }
 
-    /// <summary>
-    /// Custo estimado do pedido, <b>antes</b> da chamada. E este numero que o teto por
-    /// tenant/dia confronta e que a proveniencia grava: estimar depois e contabilidade,
-    /// estimar antes e controle.
-    /// </summary>
-    /// <remarks>
-    /// Qualidade ausente conta como <see cref="MediaQuality.Low"/> porque a escada de custo
-    /// da casa comeca em <c>low</c>; duracao ausente num pedido de video e recusa, e nao um
-    /// palpite — arbitrar segundos e arbitrar dinheiro.
-    /// </remarks>
     public MediaResult<decimal> EstimateUsd(MediaRequest request)
     {
         ArgumentNullException.ThrowIfNull(request);

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

@@ -1,36 +1,5 @@
 namespace Morph.AiKit.Media;
 
-/// <summary>
-/// A proveniencia de uma midia gerada: o que foi pedido, a quem, com que opcoes, por quanto.
-/// </summary>
-/// <remarks>
-/// <para>
-/// Gravada no momento da geracao, uma por job. Sem ela nao existe auditoria de "que modelo
-/// gerou isto", nao existe reproducao do pedido, e nao existe base para responder a uma
-/// reclamacao sobre o que a imagem mostra.
-/// </para>
-/// <para>
-/// <see cref="RevisedPrompt"/> merece o campo proprio porque o provider frequentemente
-/// reescreve o prompt antes de gerar — guardar so o enviado esconde metade do que
-/// aconteceu.
-/// </para>
-/// <para>
-/// <see cref="C2paPreserved"/> nao e enfeite: os metadados C2PA sao a unica prova tecnica
-/// de origem que a imagem carrega, e um resize "para economizar CDN" os apaga. O campo
-/// registra se o SEU pipeline os manteve. E ele nao substitui a marcacao visivel: C2PA cai
-/// com screenshot e re-encode, e <c>not_detected</c> nunca significa "feito por humano".
-/// </para>
-/// </remarks>
-/// <param name="Provider">Familia do SDK: <c>openai</c>, <c>google</c>.</param>
-/// <param name="ModelId">Id do modelo no provider — o resolvido pelo alias, nunca o alias.</param>
-/// <param name="PromptFinal">O texto efetivamente enviado, ja montado pelo template.</param>
-/// <param name="RevisedPrompt">O que o provider reescreveu, ou nulo quando ele nao devolve.</param>
-/// <param name="RefsHash">sha256 das referencias, na mesma ordem da chave de pedido.</param>
-/// <param name="Options">Forma canonica das opcoes enviadas.</param>
-/// <param name="ResponseId">Id do lado do provider, para abrir chamado.</param>
-/// <param name="EstimatedCostUsd">Custo estimado <b>antes</b> da chamada.</param>
-/// <param name="CreatedAt">Quando.</param>
-/// <param name="C2paPreserved">Se os metadados de proveniencia sobreviveram ao pipeline.</param>
 public sealed record MediaProvenance(
     string Provider,
     string ModelId,

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

@@ -2,74 +2,33 @@ using System.Security.Cryptography;
 
 namespace Morph.AiKit.Media;
 
-/// <summary>Que tipo de midia o pedido produz. Decide provider, tarifa e limites.</summary>
 public enum MediaKind
 {
-    /// <summary>Imagem.</summary>
     Image = 0,
 
-    /// <summary>Video.</summary>
     Video = 1,
 }
 
-/// <summary>
-/// Para que serve a midia pedida.
-/// </summary>
-/// <remarks>
-/// <b>E dado, nao convencao de prompt.</b> A finalidade decide qualidade minima, teto de
-/// custo, se a midia pode ser publicada e se a marcacao visivel e obrigatoria — decisoes que
-/// o codigo precisa tomar. Deixa-las implicitas numa frase do prompt e como uma regra vira
-/// folclore; as duas ultimas sao lidas por <see cref="MediaPurposeExtensions"/> e cobradas em
-/// <see cref="MediaJob.Publish"/>.
-/// </remarks>
 public enum MediaPurpose
 {
-    /// <summary>
-    /// Foto de catalogo. Revisao humana obrigatoria; qualidade alta na aprovada; marcacao
-    /// visivel obrigatoria para publicar — cobrada por <see cref="MediaJob.Publish"/>.
-    /// </summary>
     CatalogPhoto = 0,
 
-    /// <summary>
-    /// Peca de marketing. Revisao humana obrigatoria; marcacao visivel obrigatoria — e a
-    /// obrigatoriedade e COBRADA por <see cref="MediaJob.Publish"/>, nao prometida aqui.
-    /// </summary>
     Marketing = 1,
 
-    /// <summary>
-    /// Rascunho interno. <b>Nunca publicavel</b> — e <see cref="MediaJob.Publish"/> recusa,
-    /// em vez de deixar a frase valendo sozinha.
-    /// </summary>
     Draft = 2,
 }
 
-/// <summary>Qualidade pedida. <c>null</c> em <see cref="MediaOptions"/> = nao envia ao provider.</summary>
 public enum MediaQuality
 {
-    /// <summary>Candidatas. A escada de custo comeca aqui, sempre.</summary>
     Low = 0,
 
-    /// <summary>Meio-termo.</summary>
     Medium = 1,
 
-    /// <summary>So na vencedora, depois da escolha humana.</summary>
     High = 2,
 }
 
-/// <summary>
-/// Uma imagem de referencia do pedido — a foto real do produto que a edicao preserva.
-/// </summary>
-/// <remarks>
-/// <see cref="Sha256Hex"/> e calculado no construtor e entra na chave de idempotencia do
-/// PEDIDO: trocar a foto de referencia <b>e</b> outro pedido, mesmo com o prompt identico.
-/// Por isso o hash de CADA referencia participa, e nao a contagem delas.
-/// </remarks>
 public sealed class MediaReference
 {
-    /// <summary>Cria a referencia e ja fixa o hash do conteudo.</summary>
-    /// <param name="name">Como o prompt se refere a ela ("image 1 = o sofa").</param>
-    /// <param name="mediaType">MIME dos bytes.</param>
-    /// <param name="bytes">O conteudo.</param>
     public MediaReference(string name, string mediaType, ReadOnlyMemory<byte> bytes)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(name);
@@ -81,54 +40,36 @@ public sealed class MediaReference
         Sha256Hex = Convert.ToHexStringLower(SHA256.HashData(bytes.Span));
     }
 
-    /// <summary>Como o prompt indexa esta referencia.</summary>
     public string Name { get; }
 
-    /// <summary>MIME dos bytes.</summary>
     public string MediaType { get; }
 
-    /// <summary>O conteudo.</summary>
     public ReadOnlyMemory<byte> Bytes { get; }
 
-    /// <summary>sha256 do conteudo, em hex minusculo.</summary>
     public string Sha256Hex { get; }
 }
 
-/// <summary>
-/// Opcoes do pedido. <b><c>null</c> significa "nao envia ao provider"</b> — nunca "manda o
-/// default do kit": inventar default aqui e afirmar sobre o provider o que o kit nao sabe.
-/// </summary>
+// null = nao envia ao provider; inventar default aqui afirmaria sobre o provider o que o kit nao sabe.
 public sealed record MediaOptions
 {
-    /// <summary>Nenhuma opcao declarada.</summary>
     public static readonly MediaOptions None = new();
 
-    /// <summary>Qualidade pedida.</summary>
     public MediaQuality? Quality { get; init; }
 
-    /// <summary>Quantas candidatas numa chamada. Cobra por unidade.</summary>
     public int? Count { get; init; }
 
-    /// <summary>Largura em pixels.</summary>
     public int? Width { get; init; }
 
-    /// <summary>Altura em pixels.</summary>
     public int? Height { get; init; }
 
-    /// <summary>MIME de saida.</summary>
     public string? MediaType { get; init; }
 
-    /// <summary>Duracao, para video. O Veo aceita 4, 6 ou 8 s — e exige 8 s com referencias.</summary>
+    // O Veo aceita 4, 6 ou 8 s, e exige 8 s com referencias.
     public int? DurationSeconds { get; init; }
 
-    /// <summary>Proporcao, para video ("16:9", "9:16").</summary>
     public string? AspectRatio { get; init; }
 
-    /// <summary>
-    /// Forma canonica das opcoes, para a chave de idempotencia. Ordem fixa e escrita a mao
-    /// de proposito: reflexao sobre as propriedades faria a chave mudar quando alguem
-    /// reordenasse o tipo, e uma chave que muda sozinha refaz a chamada paga.
-    /// </summary>
+    // Ordem fixa e escrita a mao: reordenar o tipo nao pode mudar a chave e refazer a chamada paga.
     public string ToCanonicalString()
         => string.Join('|',
             $"quality={Quality?.ToString() ?? "-"}",
@@ -140,27 +81,14 @@ public sealed record MediaOptions
             $"ar={AspectRatio ?? "-"}");
 }
 
-/// <summary>
-/// O pedido de midia: tudo o que decide a chamada paga, e nada mais.
-/// </summary>
-/// <param name="Alias">O apelido do <c>model-registry.v2.json</c>. O pedido nunca cita modelo.</param>
-/// <param name="Prompt">O prompt final, ja montado pelo template versionado.</param>
-/// <param name="Purpose">Para que serve. Ver <see cref="MediaPurpose"/>.</param>
 public sealed record MediaRequest(string Alias, string Prompt, MediaPurpose Purpose)
 {
-    /// <summary>Imagem ou video.</summary>
     public MediaKind Kind { get; init; } = MediaKind.Image;
 
-    /// <summary>As referencias de produto. Vazio = geracao do zero.</summary>
     public IReadOnlyList<MediaReference> References { get; init; } = [];
 
-    /// <summary>As opcoes. Ver <see cref="MediaOptions"/>.</summary>
     public MediaOptions Options { get; init; } = MediaOptions.None;
 
-    /// <summary>
-    /// Recusa um pedido sem o minimo. Result, e nao excecao: pedido malformado vem de
-    /// entrada de usuario, que e caminho previsto.
-    /// </summary>
     public MediaResult<MediaRequest> Validate()
     {
         if (string.IsNullOrWhiteSpace(Alias))

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

@@ -1,59 +1,24 @@
 namespace Morph.AiKit.Media;
 
-/// <summary>
-/// Por que uma operacao de midia recusou. Discriminado por codigo, e nao por tipo de
-/// excecao, porque quem trata precisa do MOTIVO — e porque recusa aqui e caminho previsto,
-/// nunca fluxo de controle por excecao.
-/// </summary>
 public enum MediaErrorCode
 {
-    /// <summary>O pedido nao tem o minimo para ser aceito (prompt vazio, alias vazio).</summary>
     InvalidRequest = 0,
 
-    /// <summary>O teto de custo do tenant/dia recusaria a chamada. Recusa no ENQUEUE.</summary>
     BudgetExceeded = 1,
 
-    /// <summary>Falha tecnica do provider (429, 5xx, timeout). Retryable.</summary>
     ProviderFailure = 2,
 
-    /// <summary>
-    /// Bloqueio de moderacao do provider. <b>Terminal</b>: retentar gasta para receber o
-    /// mesmo "nao", e em provider que cobra o bloqueio gasta duas vezes.
-    /// </summary>
     PolicyBlocked = 3,
 
-    /// <summary>A transicao pedida nao existe a partir do estado atual do job.</summary>
     InvalidTransition = 4,
 
-    /// <summary>O job pedido nao existe no acervo do projeto.</summary>
     NotFound = 5,
 
-    /// <summary>Nao ha tarifa declarada para o alias — o custo nao pode ser estimado.</summary>
     PricingMissing = 6,
 }
 
-/// <summary>Uma recusa, com codigo e frase.</summary>
-/// <param name="Code">O motivo, para quem decide.</param>
-/// <param name="Message">A frase, para quem le o log.</param>
 public sealed record MediaError(MediaErrorCode Code, string Message);
 
-/// <summary>
-/// Result do subsistema de midia.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que <c>MediaResult</c> e nao <c>Result</c>:</b> este kit nao tem — e nao ganha
-/// aqui — um Result de proposito geral. Introduzir um tipo generico na raiz de
-/// <c>Morph.AiKit</c> e uma decisao transversal, que afeta toda superficie futura do kit e
-/// que uma feature de midia nao deve tomar de passagem. O escopo esta no nome.
-/// </para>
-/// <para>
-/// Excecao continua existindo para <b>falha de composicao</b> (argumento nulo na
-/// montagem), como na <c>AgentFactory</c>. O que nao existe e excecao para dizer "este job
-/// nao pode ser publicado neste estado": isso e informacao, e informacao viaja em Result.
-/// </para>
-/// </remarks>
-/// <typeparam name="T">O valor devolvido no sucesso.</typeparam>
 public sealed record MediaResult<T>
 {
     private readonly T _value;
@@ -65,28 +30,21 @@ public sealed record MediaResult<T>
         Error = error;
     }
 
-    /// <summary>Se a operacao produziu valor.</summary>
     public bool IsSuccess { get; }
 
-    /// <summary>A recusa, ou nulo quando <see cref="IsSuccess"/>.</summary>
     public MediaError? Error { get; }
 
-    /// <summary>O valor. Ler no caminho de falha e erro de programacao, e grita.</summary>
-    /// <exception cref="InvalidOperationException">Quando a operacao falhou.</exception>
     public T Value => IsSuccess
         ? _value
         : throw new InvalidOperationException(
             $"MediaResult<{typeof(T).Name}> em falha ({Error?.Code}): {Error?.Message}. " +
             "Confira IsSuccess antes de ler Value.");
 
-    /// <summary>Sucesso com valor.</summary>
     public static MediaResult<T> Ok(T value) => new(true, value, null);
 
-    /// <summary>Recusa nomeada.</summary>
     public static MediaResult<T> Fail(MediaErrorCode code, string message)
         => new(false, default!, new MediaError(code, message));
 
-    /// <summary>Repassa a recusa de outro Result, preservando codigo e frase.</summary>
     public static MediaResult<T> FailLike<TOther>(MediaResult<TOther> other)
         => other.Error is { } e
             ? new MediaResult<T>(false, default!, e)

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

@@ -1,37 +1,12 @@
 namespace Morph.AiKit.Media;
 
-/// <summary>O veredito de um humano sobre uma midia gerada.</summary>
 public enum MediaReviewDecision
 {
-    /// <summary>Aprovada. Unica decisao que leva a <see cref="MediaJobState.Approved"/>.</summary>
     Approved = 0,
 
-    /// <summary>Recusada.</summary>
     Rejected = 1,
 }
 
-/// <summary>
-/// Quem decidiu, o que decidiu, quando, e por que.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>"Aprovado" sem quem e sem quando nao e revisao, e um campo booleano.</b> Por isso
-/// <see cref="Reviewer"/> e <see cref="DecidedAt"/> sao obrigatorios na construcao, e a
-/// construcao recusa um revisor em branco: um carimbo anonimo nao responde a pergunta que
-/// alguem vai fazer seis meses depois.
-/// </para>
-/// <para>
-/// <b>Este tipo nao reimplementa as transicoes.</b> Elas moram no <see cref="MediaJob"/>,
-/// que e o dono do estado; os metodos estaticos daqui sao a forma conveniente de aplicar
-/// uma revisao, e delegam. Uma segunda copia da regra "so Approved publica" e exatamente
-/// como as duas divergem.
-/// </para>
-/// <para>
-/// Um juiz LLM pode preencher <see cref="Note"/> como pre-filtro, mas nao pode ser o
-/// <see cref="Reviewer"/> de um <c>CatalogPhoto</c>: ele economiza o tempo do humano, nao
-/// assume a responsabilidade por um claim visual.
-/// </para>
-/// </remarks>
 public sealed record MediaReview
 {
     private MediaReview(string reviewer, MediaReviewDecision decision, DateTimeOffset decidedAt, string? note)
@@ -42,52 +17,38 @@ public sealed record MediaReview
         Note = note;
     }
 
-    /// <summary>Identificador do humano que decidiu.</summary>
     public string Reviewer { get; }
 
-    /// <summary>O veredito.</summary>
     public MediaReviewDecision Decision { get; }
 
-    /// <summary>Quando.</summary>
     public DateTimeOffset DecidedAt { get; }
 
-    /// <summary>Observacao livre — inclusive o veredito de um juiz LLM usado como pre-filtro.</summary>
     public string? Note { get; }
 
-    /// <summary>Uma aprovacao humana.</summary>
-    /// <exception cref="ArgumentException">Revisor em branco.</exception>
     public static MediaReview ApprovedBy(string reviewer, DateTimeOffset decidedAt, string? note = null)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(reviewer);
         return new MediaReview(reviewer, MediaReviewDecision.Approved, decidedAt, note);
     }
 
-    /// <summary>Uma recusa humana.</summary>
-    /// <exception cref="ArgumentException">Revisor em branco.</exception>
     public static MediaReview RejectedBy(string reviewer, DateTimeOffset decidedAt, string? note = null)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(reviewer);
         return new MediaReview(reviewer, MediaReviewDecision.Rejected, decidedAt, note);
     }
 
-    /// <summary>Aprova o job. Delega a <see cref="MediaJob.Approve"/> — nao reimplementa a regra.</summary>
     public static MediaResult<MediaJob> Approve(MediaJob job, string reviewer, DateTimeOffset decidedAt, string? note = null)
     {
         ArgumentNullException.ThrowIfNull(job);
         return job.Approve(ApprovedBy(reviewer, decidedAt, note));
     }
 
-    /// <summary>Recusa o job. Delega a <see cref="MediaJob.Reject"/>.</summary>
     public static MediaResult<MediaJob> Reject(MediaJob job, string reviewer, DateTimeOffset decidedAt, string? note = null)
     {
         ArgumentNullException.ThrowIfNull(job);
         return job.Reject(RejectedBy(reviewer, decidedAt, note));
     }
 
-    /// <summary>
-    /// Publica o job. Delega a <see cref="MediaJob.Publish"/>, que cobra as tres portas
-    /// (estado Approved, finalidade publicavel, marcacao quando exigida).
-    /// </summary>
     public static MediaResult<MediaJob> Publish(
         MediaJob job,
         MediaDisclosure? disclosure,

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

@@ -1,18 +1,5 @@
 namespace Morph.AiKit.Media;
 
-/// <summary>
-/// A resolucao de um alias de midia: para quem ir, com que modelo, por qual tarifa.
-/// </summary>
-/// <remarks>
-/// O pedido cita o <b>alias</b>; a chave de idempotencia e a proveniencia citam o
-/// <b>modelo</b>. A diferenca importa: um alias pode ser repontado para outro modelo, e
-/// duas geracoes com o mesmo alias e modelos diferentes nao sao o mesmo pedido.
-/// </remarks>
-/// <param name="Alias">O apelido citado pelo pedido.</param>
-/// <param name="Provider">Familia do SDK.</param>
-/// <param name="Model">O id do modelo no provider.</param>
-/// <param name="Kind">Imagem ou video.</param>
-/// <param name="Pricing">A tarifa, na unidade certa. Ver <see cref="MediaPricing"/>.</param>
 public sealed record MediaAliasBinding(
     string Alias,
     string Provider,
@@ -20,78 +7,37 @@ public sealed record MediaAliasBinding(
     MediaKind Kind,
     MediaPricing Pricing);
 
-/// <summary>Resolve um alias de midia. Alias desconhecido e recusa nomeada, nunca nulo.</summary>
 public interface IMediaAliasResolver
 {
-    /// <summary>O binding do alias.</summary>
     MediaResult<MediaAliasBinding> Resolve(string alias);
 }
 
-/// <summary>
-/// Onde os jobs ficam guardados. <b>A costura entre o kit e o banco do projeto.</b>
-/// </summary>
-/// <remarks>
-/// Sem tipo de infraestrutura na assinatura, pela mesma razao de
-/// <c>IConversationStore</c>: o kit nao conhece banco. No projeto, o handler fala com o
-/// <c>ApplicationDbContext</c> direto — sem camada de service, sem repository generico.
-/// Dentro de um job, <c>IDbContextFactory</c>, como o standard de Hangfire ja exige.
-/// </remarks>
 public interface IMediaJobRepository
 {
-    /// <summary>
-    /// O job de mesma chave de PEDIDO, se existir. <b>E a consulta que evita pagar duas
-    /// vezes</b>, e por isso ela vem antes de qualquer chamada ao provider.
-    /// </summary>
     ValueTask<MediaJob?> FindByIdempotencyKeyAsync(MediaIdempotencyKey key, CancellationToken cancellationToken);
 
-    /// <summary>O job por id, ou nulo.</summary>
     ValueTask<MediaJob?> FindAsync(MediaJobId id, CancellationToken cancellationToken);
 
-    /// <summary>Grava o estado corrente do job.</summary>
     ValueTask SaveAsync(MediaJob job, CancellationToken cancellationToken);
 }
 
-/// <summary>
-/// O teto de custo por tenant/dia.
-/// </summary>
-/// <remarks>
-/// <b>A reserva acontece no ENQUEUE</b>, com o custo estimado ANTES da chamada. Um alerta
-/// que chega depois da chamada e contabilidade, nao controle: o dinheiro ja saiu.
-/// </remarks>
 public interface IMediaBudget
 {
-    /// <summary>
-    /// Reserva o custo estimado. <c>false</c> = estourou o teto, e o enqueue recusa com
-    /// <see cref="MediaErrorCode.BudgetExceeded"/>.
-    /// </summary>
+    // Reservado no ENQUEUE, antes da chamada: alerta depois dela e contabilidade, nao controle.
     ValueTask<bool> TryReserveAsync(MediaRequest request, decimal estimatedCostUsd, CancellationToken cancellationToken);
 }
 
-/// <summary>
-/// Executa UM job: chama o provider, guarda os bytes, move o estado.
-/// </summary>
-/// <remarks>
-/// A interface e publica para que o <c>BackgroundService</c> do projeto (ou o job Hangfire)
-/// possa dispara-la; a <b>implementacao</b> e <c>internal</c>, porque e ela que segura o
-/// <c>IMediaProvider</c>. Um handler pode pedir "rode este job"; nao pode pedir "gere estes
-/// bytes agora".
-/// </remarks>
 public interface IMediaJobRunner
 {
-    /// <summary>Roda o job ate o proximo estado estavel e devolve como ele ficou.</summary>
     Task<MediaResult<MediaJob>> RunAsync(MediaJobId id, CancellationToken cancellationToken = default);
 }
 
-/// <summary>Relogio, para que o carimbo de tempo seja testavel sem esperar o mundo girar.</summary>
 public interface IMediaClock
 {
-    /// <summary>Agora.</summary>
     DateTimeOffset UtcNow { get; }
 }
 
-/// <summary>O relogio do sistema.</summary>
 public sealed class SystemMediaClock : IMediaClock
 {
-    /// <inheritdoc />
     public DateTimeOffset UtcNow => DateTimeOffset.UtcNow;
 }

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

@@ -2,98 +2,43 @@ using System.Security.Cryptography;
 
 namespace Morph.AiKit.Media;
 
-/// <summary>
-/// O endereco de um conteudo: sha256 dos BYTES.
-/// </summary>
-/// <remarks>
-/// Responde "ja guardamos isto?" — nunca "ja pagamos por isto?", que e a pergunta do
-/// <see cref="MediaIdempotencyKey"/>. Confundir as duas e o defeito caro: dois pedidos
-/// diferentes podem produzir bytes identicos (e devem compartilhar UM arquivo), e o mesmo
-/// pedido nunca deve ser pago duas vezes (mesmo que os bytes saiam diferentes).
-/// </remarks>
-/// <param name="Value">sha256 em hex minusculo.</param>
+// Endereca BYTES ("ja guardamos?"), nunca o pedido ("ja pagamos?"), que e o MediaIdempotencyKey.
 public readonly record struct MediaHash(string Value)
 {
-    /// <summary>O hash do conteudo.</summary>
     public static MediaHash Of(ReadOnlySpan<byte> bytes)
         => new(Convert.ToHexStringLower(SHA256.HashData(bytes)));
 
-    /// <summary>O hash, para log e para o caminho no blob.</summary>
     public override string ToString() => Value;
 }
 
-/// <summary>
-/// Onde os bytes ficam guardados. <b>A costura entre o kit e o blob do projeto</b> — o
-/// unico ponto do <see cref="MediaStore"/> que um projeto precisa implementar.
-/// </summary>
-/// <remarks>
-/// Deliberadamente sem tipo de infraestrutura na assinatura: nenhum <c>BlobClient</c>,
-/// nenhum <c>S3</c>, nenhum caminho absoluto. A implementacao de producao vive no projeto;
-/// a de teste vive nos fakes da suite. O kit nao conhece storage, pela mesma razao pela
-/// qual <c>IConversationStore</c> nao conhece banco.
-/// </remarks>
 public interface IMediaBlobs
 {
-    /// <summary>Se o caminho relativo ja existe. Nunca lanca por ausencia.</summary>
     ValueTask<bool> ExistsAsync(string relativePath, CancellationToken cancellationToken);
 
-    /// <summary>Grava o conteudo no caminho relativo.</summary>
     ValueTask WriteAsync(string relativePath, ReadOnlyMemory<byte> bytes, CancellationToken cancellationToken);
 }
 
-/// <summary>O que o storage devolve sobre um conteudo guardado.</summary>
-/// <param name="Hash">sha256 dos bytes.</param>
-/// <param name="RelativePath">
-/// O caminho RELATIVO, que e o que o banco guarda. Caminho absoluto ou URL de provider
-/// amarram a linha ao disco de hoje ou a uma URL que expira — o Veo apaga o arquivo em 2
-/// dias, e todo agregador devolve URL temporaria.
-/// </param>
-/// <param name="MediaType">MIME.</param>
-/// <param name="AlreadyExisted">
-/// Se o conteudo ja estava la. <b>Nao e enfeite:</b> e como o chamador sabe que a gravacao
-/// foi deduplicada em vez de repetida.
-/// </param>
+// Caminho RELATIVO, nunca URL de provider: o Veo apaga o arquivo em 2 dias e agregadores devolvem URL temporaria.
 public sealed record MediaStoreEntry(MediaHash Hash, string RelativePath, string MediaType, bool AlreadyExisted);
 
-/// <summary>Storage de midia enderecado por conteudo.</summary>
 public interface IMediaStore
 {
-    /// <summary>Guarda os bytes e devolve o endereco. Conteudo repetido NAO e regravado.</summary>
     ValueTask<MediaStoreEntry> PutAsync(
         ReadOnlyMemory<byte> bytes,
         string mediaType,
         CancellationToken cancellationToken);
 }
 
-/// <summary>
-/// Storage enderecado por conteudo: o caminho e derivado do sha256, e gravar o mesmo
-/// conteudo duas vezes grava uma.
-/// </summary>
-/// <remarks>
-/// <para>
-/// O caminho e <c>ab/cd/&lt;hash&gt;.&lt;ext&gt;</c>. Os dois niveis de prefixo existem
-/// porque um diretorio unico com centenas de milhares de arquivos degrada listagem em
-/// praticamente todo sistema de arquivos e em varios object stores.
-/// </para>
-/// <para>
-/// A extensao vem do MIME e e o unico lugar do subsistema que faz esse mapa. Um MIME
-/// desconhecido vira <c>.bin</c> em vez de recusa: perder a extensao e cosmetico, perder os
-/// bytes pelos quais se pagou nao e.
-/// </para>
-/// </remarks>
 public sealed class MediaStore : IMediaStore
 {
     private readonly IMediaBlobs _blobs;
 
-    /// <summary>Cria o storage sobre o blob do projeto.</summary>
-    /// <exception cref="ArgumentNullException">Blob nulo.</exception>
     public MediaStore(IMediaBlobs blobs)
     {
         ArgumentNullException.ThrowIfNull(blobs);
         _blobs = blobs;
     }
 
-    /// <inheritdoc />
     public async ValueTask<MediaStoreEntry> PutAsync(
         ReadOnlyMemory<byte> bytes,
         string mediaType,
@@ -113,14 +58,13 @@ public sealed class MediaStore : IMediaStore
         return new MediaStoreEntry(hash, path, mediaType, AlreadyExisted: false);
     }
 
-    /// <summary>O caminho relativo de um conteudo. Puro, para poder ser conferido em teste.</summary>
+    // Dois niveis de prefixo: um diretorio com centenas de milhares de arquivos degrada a listagem.
     public static string RelativePathFor(MediaHash hash, string mediaType)
     {
         var value = hash.Value;
         return $"{value[..2]}/{value[2..4]}/{value}{ExtensionFor(mediaType)}";
     }
 
-    /// <summary>MIME para extensao de arquivo. Desconhecido vira <c>.bin</c>, nunca recusa.</summary>
     public static string ExtensionFor(string mediaType) => mediaType.ToLowerInvariant() switch
     {
         "image/png" => ".png",