@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

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

@@ -0,0 +1,97 @@
+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,
+    string Model,
+    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>
+    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

@@ -0,0 +1,133 @@
+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>
+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>
+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,
+        CancellationToken cancellationToken)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(mediaType);
+
+        var hash = MediaHash.Of(bytes.Span);
+        var path = RelativePathFor(hash, mediaType);
+
+        if (await _blobs.ExistsAsync(path, cancellationToken).ConfigureAwait(false))
+        {
+            return new MediaStoreEntry(hash, path, mediaType, AlreadyExisted: true);
+        }
+
+        await _blobs.WriteAsync(path, bytes, cancellationToken).ConfigureAwait(false);
+        return new MediaStoreEntry(hash, path, mediaType, AlreadyExisted: false);
+    }
+
+    /// <summary>O caminho relativo de um conteudo. Puro, para poder ser conferido em teste.</summary>
+    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",
+        "image/jpeg" or "image/jpg" => ".jpg",
+        "image/webp" => ".webp",
+        "video/mp4" => ".mp4",
+        "video/webm" => ".webm",
+        _ => ".bin",
+    };
+}

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

@@ -0,0 +1,93 @@
+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);
+        ArgumentNullException.ThrowIfNull(options.AliasResolver);
+        ArgumentNullException.ThrowIfNull(options.Jobs);
+        ArgumentNullException.ThrowIfNull(options.Store);
+        ArgumentNullException.ThrowIfNull(options.Clients);
+
+        var clock = options.Clock ?? new SystemMediaClock();
+
+        var generator = new MediaGenerator(
+            options.AliasResolver,
+            options.Jobs,
+            options.Budget,
+            clock);
+
+        var runner = new MediaWorker(
+            options.AliasResolver,
+            options.Jobs,
+            options.Store,
+            MediaProviderCatalog.Build(options.Clients),
+            clock);
+
+        return new MorphMediaComponents(generator, runner);
+    }
+}
+
+/// <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);

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

@@ -0,0 +1,112 @@
+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>
+internal sealed class GoogleImageProvider : IMediaProvider
+{
+    private readonly IMediaClientFactory _clients;
+
+    public GoogleImageProvider(IMediaClientFactory clients)
+    {
+        ArgumentNullException.ThrowIfNull(clients);
+        _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,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ArgumentNullException.ThrowIfNull(binding);
+
+        var client = _clients.CreateGoogleClient(binding);
+        if (client is null)
+        {
+            return MediaResult<MediaArtifact>.Fail(
+                MediaErrorCode.ProviderFailure,
+                $"alias '{binding.Alias}': a fabrica de clientes nao construiu um Google.GenAI.Client.");
+        }
+
+        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.
+        foreach (var reference in request.References)
+        {
+            parts.Add(new Part
+            {
+                InlineData = new Blob
+                {
+                    Data = reference.Bytes.ToArray(),
+                    MimeType = reference.MediaType,
+                    DisplayName = reference.Name,
+                },
+            });
+        }
+
+        var config = new GenerateContentConfig
+        {
+            ResponseModalities = ["IMAGE", "TEXT"],
+        };
+
+        var response = await client.Models
+            .GenerateContentAsync(
+                binding.Model,
+                new Content { Role = "user", Parts = parts },
+                config,
+                cancellationToken)
+            .ConfigureAwait(false);
+
+        var blob = response.Candidates?
+            .SelectMany(c => c.Content?.Parts ?? [])
+            .Select(p => p.InlineData)
+            .FirstOrDefault(d => d?.Data is { Length: > 0 });
+
+        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 " +
+                "conteudo — e um bloqueio nao vira retry, porque retentar recebe o mesmo 'nao'.");
+        }
+
+        return MediaResult<MediaArtifact>.Ok(new MediaArtifact(
+            MediaKind.Image,
+            blob.MimeType ?? "image/png",
+            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.
+            C2paPreserved: true));
+    }
+}