@polymorphism-tech/morph-spec 8.38.0 → 8.41.0

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",

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

@@ -1,65 +1,22 @@
 namespace Morph.AiKit.Media;
 
-/// <summary>
-/// As pecas que o projeto precisa fornecer para o subsistema de midia funcionar.
-/// </summary>
-/// <remarks>
-/// Nenhuma delas produz bytes. Repare no que NAO ha aqui: nao ha como o projeto injetar,
-/// substituir ou alcancar um <c>IMediaProvider</c> — os adaptadores sao montados dentro do
-/// assembly, por <see cref="MorphMedia"/>.
-/// </remarks>
 public sealed record MorphMediaOptions
 {
-    /// <summary>Resolve alias para provider/modelo/tarifa. Obrigatorio.</summary>
     public required IMediaAliasResolver AliasResolver { get; init; }
 
-    /// <summary>Onde os jobs vivem. Obrigatorio.</summary>
     public required IMediaJobRepository Jobs { get; init; }
 
-    /// <summary>Onde os bytes vivem. Obrigatorio.</summary>
     public required IMediaStore Store { get; init; }
 
-    /// <summary>
-    /// Constroi os clientes de SDK. Obrigatorio — e a costura com o provider de verdade.
-    /// </summary>
     public required IMediaClientFactory Clients { get; init; }
 
-    /// <summary>O teto de custo. Nulo = sem teto (aceitavel so em ambiente de desenvolvimento).</summary>
     public IMediaBudget? Budget { get; init; }
 
-    /// <summary>O relogio. Nulo = relogio do sistema.</summary>
     public IMediaClock? Clock { get; init; }
 }
 
-/// <summary>
-/// A raiz de composicao do subsistema de midia.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que uma fabrica estatica e nao um <c>AddMorphMedia(IServiceCollection)</c>:</b>
-/// uma extensao de DI exigiria uma <c>PackageReference</c> explicita a
-/// <c>Microsoft.Extensions.DependencyInjection.Abstractions</c>, e neste repositorio as
-/// versoes de pacote sao GERADAS de <c>framework/ai-pin.json</c>. Acrescentar um pacote e
-/// mexer no pin — uma decisao que se toma de proposito, com re-verificacao, e nao de
-/// passagem numa feature de midia. Depender do pacote de forma TRANSITIVA seria pior: uma
-/// dependencia escondida, que some no dia em que a arvore de dependencias mudar.
-/// </para>
-/// <para>
-/// No projeto consumidor, o registro e uma linha, e o kit continua sem conhecer DI:
-/// </para>
-/// <code>
-/// var media = MorphMedia.Create(options);
-/// builder.Services.AddSingleton&lt;IMediaGenerator&gt;(media.Generator);
-/// builder.Services.AddSingleton&lt;IMediaJobRunner&gt;(media.Runner);
-/// </code>
-/// </remarks>
 public static class MorphMedia
 {
-    /// <summary>
-    /// Monta o subsistema: o gerador publico e o executor de job, ambos sobre os mesmos
-    /// adaptadores internos.
-    /// </summary>
-    /// <exception cref="ArgumentNullException">Opcoes nulas.</exception>
     public static MorphMediaComponents Create(MorphMediaOptions options)
     {
         ArgumentNullException.ThrowIfNull(options);
@@ -87,7 +44,4 @@ public static class MorphMedia
     }
 }
 
-/// <summary>O que a raiz de composicao devolve. Duas interfaces, nenhuma delas com bytes.</summary>
-/// <param name="Generator">O ponto de entrada do pedido.</param>
-/// <param name="Runner">O executor de job, para o <c>BackgroundService</c> do projeto.</param>
 public sealed record MorphMediaComponents(IMediaGenerator Generator, IMediaJobRunner Runner);