@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/MediaGeneratorTests.cs

@@ -0,0 +1,264 @@
+using System.Text;
+using Morph.AiKit.Media;
+using Morph.AiKit.Tests.Fakes;
+using Xunit;
+
+namespace Morph.AiKit.Tests;
+
+/// <summary>
+/// Canarios do enqueue e do worker. <b>Nenhum deles toca API paga</b> — o unico ponto que
+/// gastaria dinheiro e o <see cref="FakeMediaProvider"/>, e a suite conta as chamadas dele.
+/// </summary>
+/// <remarks>
+/// As afirmacoes aqui sao as tres que o dinheiro cobra: um retry nao paga de novo, um
+/// estouro de teto recusa <b>antes</b> da chamada, e um bloqueio de moderacao vai para
+/// <c>RejectedByPolicy</c> em vez de virar retry.
+/// </remarks>
+public sealed class MediaGeneratorTests
+{
+    private static readonly DateTimeOffset T0 = new(2026, 9, 8, 12, 0, 0, TimeSpan.Zero);
+
+    private static CancellationToken Ct => TestContext.Current.CancellationToken;
+
+    private static MediaAliasBinding ImageBinding(decimal low = 0.006m) => new(
+        "catalogo", "fake", "gpt-image-2", MediaKind.Image, MediaPricing.PerImage(low, 0.053m, 0.211m));
+
+    private static MediaRequest Request(MediaOptions? options = null)
+        => new("catalogo", "um sofa verde", MediaPurpose.CatalogPhoto) { Options = options ?? MediaOptions.None };
+
+    private static (MediaGenerator Generator, MediaWorker Worker, InMemoryMediaJobs Jobs,
+        InMemoryMediaStore Store, FakeMediaProvider Provider) Build(
+            IMediaBudget? budget = null, MediaAliasBinding? binding = null)
+    {
+        var aliases = new StubAliasResolver().With(binding ?? ImageBinding());
+        var jobs = new InMemoryMediaJobs();
+        var store = new InMemoryMediaStore();
+        var provider = new FakeMediaProvider(provider: "fake");
+        var clock = new FixedMediaClock(T0);
+
+        return (
+            new MediaGenerator(aliases, jobs, budget, clock),
+            new MediaWorker(aliases, jobs, store, [provider], clock),
+            jobs, store, provider);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Enqueue: id de job, nunca bytes
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>Um pedido valido vira job em <c>Pending</c>, e o retorno e um id.</summary>
+    [Fact]
+    public async Task EnqueueReturnsAJobIdAndTheJobStartsPending()
+    {
+        var (generator, _, _, _, provider) = Build();
+
+        var enqueued = await generator.EnqueueAsync(Request(), Ct);
+
+        Assert.True(enqueued.IsSuccess);
+        var job = await generator.GetAsync(enqueued.Value, Ct);
+        Assert.Equal(MediaJobState.Pending, job.Value.State);
+
+        // Nada foi gasto: o enqueue NAO chama provider.
+        Assert.Equal(0, provider.Calls);
+    }
+
+    /// <summary>Pedido sem prompt e recusa nomeada, nao excecao.</summary>
+    [Fact]
+    public async Task AnInvalidRequestIsRefusedByName()
+    {
+        var (generator, _, _, _, _) = Build();
+
+        var result = await generator.EnqueueAsync(
+            new MediaRequest("catalogo", "   ", MediaPurpose.Draft), Ct);
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal(MediaErrorCode.InvalidRequest, result.Error!.Code);
+    }
+
+    /// <summary>Alias desconhecido: recusa, e nenhum job criado.</summary>
+    [Fact]
+    public async Task AnUnknownAliasIsRefused()
+    {
+        var (generator, _, jobs, _, _) = Build();
+
+        var result = await generator.EnqueueAsync(
+            new MediaRequest("inexistente", "p", MediaPurpose.Draft), Ct);
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal(0, jobs.Saves);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Idempotencia: o retry nao paga de novo
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// O MESMO pedido, enfileirado duas vezes, devolve o MESMO job. E o que faz um retry de
+    /// fila, de worker reiniciado ou de webhook duplicado custar zero.
+    /// </summary>
+    [Fact]
+    public async Task TheSameRequestEnqueuedTwiceReusesTheSameJob()
+    {
+        var (generator, _, jobs, _, _) = Build();
+
+        var first = await generator.EnqueueAsync(Request(), Ct);
+        var second = await generator.EnqueueAsync(Request(), Ct);
+
+        Assert.Equal(first.Value, second.Value);
+        Assert.Equal(1, jobs.Saves);
+    }
+
+    /// <summary>Pedido diferente, job diferente — a dedupe nao pode engolir trabalho novo.</summary>
+    [Fact]
+    public async Task ADifferentRequestGetsItsOwnJob()
+    {
+        var (generator, _, _, _, _) = Build();
+
+        var first = await generator.EnqueueAsync(Request(), Ct);
+        var second = await generator.EnqueueAsync(
+            new MediaRequest("catalogo", "um sofa azul", MediaPurpose.CatalogPhoto), Ct);
+
+        Assert.NotEqual(first.Value, second.Value);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Teto de custo: recusa ANTES da chamada
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// O teto e confrontado com o custo estimado, e a recusa acontece no enqueue — antes de
+    /// existir qualquer chamada. Depois dela, o dinheiro ja saiu.
+    /// </summary>
+    [Fact]
+    public async Task ABudgetOverrunIsRefusedAtEnqueueBeforeAnyCall()
+    {
+        var budget = new CappedBudget(0.01m);
+        var (generator, _, jobs, _, provider) = Build(budget);
+
+        var result = await generator.EnqueueAsync(
+            Request(new MediaOptions { Quality = MediaQuality.High }), Ct);
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal(MediaErrorCode.BudgetExceeded, result.Error!.Code);
+        Assert.Equal(0, jobs.Saves);
+        Assert.Equal(0, provider.Calls);
+        Assert.Equal([0.211m], budget.Seen);
+    }
+
+    /// <summary>O custo estimado que chega ao teto e o da tarifa, na quantidade pedida.</summary>
+    [Fact]
+    public async Task TheEstimateSentToTheBudgetIsTariffTimesCount()
+    {
+        var budget = new CappedBudget(100m);
+        var (generator, _, _, _, _) = Build(budget);
+
+        _ = await generator.EnqueueAsync(Request(new MediaOptions { Count = 4 }), Ct);
+
+        Assert.Equal([0.024m], budget.Seen);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Worker: estados, storage e a distincao que vale dinheiro
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>Caminho feliz: os bytes vao para o storage ANTES de o job virar Generated.</summary>
+    [Fact]
+    public async Task TheWorkerStoresTheBytesAndThenMarksGenerated()
+    {
+        var (generator, worker, _, store, provider) = Build();
+        provider.Returns(Encoding.UTF8.GetBytes("os bytes"), "image/png", "prompt reescrito");
+
+        var id = (await generator.EnqueueAsync(Request(), Ct)).Value;
+        var ran = await worker.RunAsync(id, Ct);
+
+        Assert.True(ran.IsSuccess);
+        Assert.Equal(MediaJobState.Generated, ran.Value.State);
+        Assert.Equal(1, store.Blobs.Writes);
+        Assert.Equal(MediaHash.Of(Encoding.UTF8.GetBytes("os bytes")), ran.Value.Hash);
+        Assert.EndsWith(".png", ran.Value.RelativePath, StringComparison.Ordinal);
+    }
+
+    /// <summary>A proveniencia e gravada com o modelo, o prompt reescrito e o custo estimado.</summary>
+    [Fact]
+    public async Task TheWorkerRecordsProvenanceWithTheEstimatedCost()
+    {
+        var (generator, worker, _, _, provider) = Build();
+        provider.Returns(Encoding.UTF8.GetBytes("x"), "image/png", "prompt reescrito");
+
+        var id = (await generator.EnqueueAsync(Request(), Ct)).Value;
+        var provenance = (await worker.RunAsync(id, Ct)).Value.Provenance;
+
+        Assert.NotNull(provenance);
+        Assert.Equal("gpt-image-2", provenance.ModelId);
+        Assert.Equal("fake", provenance.Provider);
+        Assert.Equal("prompt reescrito", provenance.RevisedPrompt);
+        Assert.Equal(0.006m, provenance.EstimatedCostUsd);
+        Assert.Equal(T0, provenance.CreatedAt);
+        Assert.True(provenance.C2paPreserved);
+    }
+
+    /// <summary>
+    /// Bloqueio de moderacao vira <c>RejectedByPolicy</c>, terminal. Um erro tecnico vira
+    /// <c>Failed</c>, retryable. Colapsar os dois e como um laco de retry vira fatura.
+    /// </summary>
+    [Theory]
+    [InlineData(MediaErrorCode.PolicyBlocked, MediaJobState.RejectedByPolicy, false)]
+    [InlineData(MediaErrorCode.ProviderFailure, MediaJobState.Failed, true)]
+    public async Task TheWorkerSeparatesPolicyBlocksFromTechnicalFailures(
+        MediaErrorCode produced, MediaJobState expected, bool retryable)
+    {
+        var (generator, worker, _, store, provider) = Build();
+        provider.Fails(produced);
+
+        var id = (await generator.EnqueueAsync(Request(), Ct)).Value;
+        var ran = await worker.RunAsync(id, Ct);
+
+        Assert.Equal(expected, ran.Value.State);
+        Assert.Equal(retryable, ran.Value.IsRetryable);
+        Assert.Equal(0, store.Blobs.Writes);
+    }
+
+    /// <summary>Job inexistente e recusa nomeada, nunca uma excecao de referencia nula.</summary>
+    [Fact]
+    public async Task RunningAnUnknownJobIsRefusedByName()
+    {
+        var (_, worker, _, _, _) = Build();
+
+        var ran = await worker.RunAsync(MediaJobId.New(), Ct);
+
+        Assert.False(ran.IsSuccess);
+        Assert.Equal(MediaErrorCode.NotFound, ran.Error!.Code);
+    }
+
+    /// <summary>
+    /// Um alias de VIDEO pedido como imagem nao vira job: as unidades de cobranca sao
+    /// diferentes, e um pedido com a tarifa errada estima o custo errado em silencio.
+    /// </summary>
+    [Fact]
+    public async Task AVideoAliasCannotServeAnImageRequest()
+    {
+        var (generator, _, _, _, _) = Build(binding: new MediaAliasBinding(
+            "catalogo", "fake", "veo-3.1-fast-generate-preview", MediaKind.Video, MediaPricing.PerSecond(0.10m)));
+
+        var result = await generator.EnqueueAsync(Request(), Ct);
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal(MediaErrorCode.InvalidRequest, result.Error!.Code);
+    }
+
+    /// <summary>
+    /// Video sem duracao nao tem custo estimavel — e arbitrar segundos e arbitrar dinheiro.
+    /// </summary>
+    [Fact]
+    public async Task AVideoRequestWithoutDurationCannotBePriced()
+    {
+        var (generator, _, _, _, _) = Build(binding: new MediaAliasBinding(
+            "catalogo", "fake", "veo", MediaKind.Video, MediaPricing.PerSecond(0.10m)));
+
+        var result = await generator.EnqueueAsync(
+            new MediaRequest("catalogo", "um reel", MediaPurpose.Marketing) { Kind = MediaKind.Video }, Ct);
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal(MediaErrorCode.PricingMissing, result.Error!.Code);
+    }
+}

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/MediaIdempotencyKeyTests.cs

@@ -0,0 +1,148 @@
+using System.Text;
+using Morph.AiKit.Media;
+using Xunit;
+
+namespace Morph.AiKit.Tests;
+
+/// <summary>
+/// Canarios de <see cref="MediaIdempotencyKey"/>: a chave que dedupe a CHAMADA PAGA.
+/// </summary>
+/// <remarks>
+/// Duas propriedades, e as duas custam dinheiro quando falham. <b>Estabilidade</b>: o mesmo
+/// pedido tem de dar a mesma chave, senao todo retry paga de novo. <b>Sensibilidade</b>:
+/// qualquer campo participante que mude tem de mudar a chave, senao um pedido reusa o
+/// artefato pago de OUTRO — pior que pagar duas vezes.
+/// </remarks>
+public sealed class MediaIdempotencyKeyTests
+{
+    private static MediaRequest Request(
+        string prompt = "um sofa verde",
+        MediaOptions? options = null,
+        params string[] references)
+        => new("catalogo", prompt, MediaPurpose.CatalogPhoto)
+        {
+            Options = options ?? MediaOptions.None,
+            References = [.. references.Select(r =>
+                new MediaReference(r, "image/png", Encoding.UTF8.GetBytes(r)))],
+        };
+
+    private static string KeyOf(MediaRequest request)
+        => MediaIdempotencyKey.From(request, "openai", "gpt-image-2").Value;
+
+    // ---------------------------------------------------------------------------------
+    // Estabilidade
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>Duas construcoes do mesmo pedido dao a mesma chave.</summary>
+    [Fact]
+    public void TheSameRequestAlwaysGivesTheSameKey()
+        => Assert.Equal(KeyOf(Request()), KeyOf(Request()));
+
+    /// <summary>
+    /// Espaco em branco a mais nao muda o pedido, entao nao muda a chave. E o que impede um
+    /// prompt re-serializado com quebra de linha diferente de virar outra fatura.
+    /// </summary>
+    [Fact]
+    public void WhitespaceIsNormalisedAway()
+        => Assert.Equal(KeyOf(Request("um sofa verde")), KeyOf(Request("  um   sofa\n verde  ")));
+
+    /// <summary>
+    /// A caixa NAO e normalizada, e e deliberado: num prompt ela muda o resultado (nome de
+    /// marca, texto literal que vai aparecer na imagem).
+    /// </summary>
+    [Fact]
+    public void CaseIsPreservedBecauseItChangesThePicture()
+        => Assert.NotEqual(KeyOf(Request("um sofa VERDE")), KeyOf(Request("um sofa verde")));
+
+    /// <summary>A chave e um sha256 em hex minusculo: 64 digitos.</summary>
+    [Fact]
+    public void TheKeyIsASha256InLowercaseHex()
+    {
+        var key = KeyOf(Request());
+
+        Assert.Equal(64, key.Length);
+        Assert.Matches("^[0-9a-f]{64}$", key);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Sensibilidade — uma rodada POR CAMPO participante
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>Prompt diferente, chave diferente.</summary>
+    [Fact]
+    public void ADifferentPromptChangesTheKey()
+        => Assert.NotEqual(KeyOf(Request("um sofa azul")), KeyOf(Request()));
+
+    /// <summary>Modelo diferente, chave diferente — o alias pode ser repontado.</summary>
+    [Fact]
+    public void ADifferentModelChangesTheKey()
+        => Assert.NotEqual(
+            MediaIdempotencyKey.From(Request(), "openai", "gpt-image-2").Value,
+            MediaIdempotencyKey.From(Request(), "openai", "outro-modelo").Value);
+
+    /// <summary>Provider diferente, chave diferente.</summary>
+    [Fact]
+    public void ADifferentProviderChangesTheKey()
+        => Assert.NotEqual(
+            MediaIdempotencyKey.From(Request(), "openai", "m").Value,
+            MediaIdempotencyKey.From(Request(), "google", "m").Value);
+
+    /// <summary>
+    /// <b>Trocar a foto de referencia E outro pedido</b>, mesmo com o prompt identico. Por
+    /// isso o sha256 de CADA referencia participa, e nao a contagem delas.
+    /// </summary>
+    [Fact]
+    public void ADifferentReferenceChangesTheKey()
+        => Assert.NotEqual(
+            KeyOf(Request(references: ["foto-a"])),
+            KeyOf(Request(references: ["foto-b"])));
+
+    /// <summary>Mesma quantidade de referencias, conteudo trocado de ordem: outro pedido.</summary>
+    [Fact]
+    public void TheOrderOfReferencesIsPartOfTheRequest()
+        => Assert.NotEqual(
+            KeyOf(Request(references: ["a", "b"])),
+            KeyOf(Request(references: ["b", "a"])));
+
+    /// <summary>Sem referencia e com referencia sao pedidos diferentes.</summary>
+    [Fact]
+    public void AddingAReferenceChangesTheKey()
+        => Assert.NotEqual(KeyOf(Request()), KeyOf(Request(references: ["foto-a"])));
+
+    /// <summary>Cada opcao participante, uma rodada.</summary>
+    [Theory]
+    [MemberData(nameof(OptionVariations))]
+    public void EveryParticipatingOptionChangesTheKey(MediaOptions variation)
+        => Assert.NotEqual(KeyOf(Request()), KeyOf(Request(options: variation)));
+
+    /// <summary>As variacoes de opcao exercitadas, uma por campo canonico.</summary>
+    public static TheoryData<MediaOptions> OptionVariations() =>
+    [
+        new MediaOptions { Quality = MediaQuality.High },
+        new MediaOptions { Count = 4 },
+        new MediaOptions { Width = 1024, Height = 1024 },
+        new MediaOptions { MediaType = "image/webp" },
+        new MediaOptions { DurationSeconds = 8 },
+        new MediaOptions { AspectRatio = "9:16" },
+    ];
+
+    /// <summary>
+    /// O separador e um caractere de CONTROLE, e nao <c>|</c>. Um prompt que contivesse o
+    /// separador visivel emendaria campos e faria dois pedidos diferentes colidirem — que
+    /// e o defeito que faz um pedido reusar o artefato pago do outro.
+    /// </summary>
+    [Fact]
+    public void APromptFullOfPipesDoesNotCollideWithAnotherRequest()
+        => Assert.NotEqual(
+            KeyOf(Request("gpt-image-2|Image|um sofa")),
+            KeyOf(Request("um sofa")));
+
+    /// <summary>Normalizacao de prompt e pura e conferivel sozinha.</summary>
+    [Theory]
+    [InlineData("  a  b  ", "a b")]
+    [InlineData("a\n\nb", "a b")]
+    [InlineData("", "")]
+    [InlineData("   ", "")]
+    public void NormalizePromptCollapsesWhitespace(string input, string expected)
+        => Assert.Equal(expected, MediaIdempotencyKey.NormalizePrompt(input));
+}

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/MediaJobStateTests.cs

@@ -0,0 +1,184 @@
+using Morph.AiKit.Media;
+using Xunit;
+
+namespace Morph.AiKit.Tests;
+
+/// <summary>
+/// Canarios da maquina de estados de <see cref="MediaJob"/>.
+/// </summary>
+/// <remarks>
+/// Tres afirmacoes carregam o standard <c>ai-agents/media-pipeline.md</c> inteiro, e cada
+/// uma e o inverso literal de um defeito caro:
+/// <list type="number">
+///   <item><c>Publish</c> falha fora de <c>Approved</c> — publicar sem revisao humana.</item>
+///   <item><c>Approved</c> so existe por <c>Approve(revisor)</c> — "aprovado" sem quem.</item>
+///   <item><c>RejectedByPolicy</c> nao e retryable — retry que vira fatura.</item>
+/// </list>
+/// </remarks>
+public sealed class MediaJobStateTests
+{
+    private static readonly DateTimeOffset T0 = new(2026, 9, 8, 12, 0, 0, TimeSpan.Zero);
+
+    /// <summary>Uma marcacao valida, para os casos que nao estao medindo a marcacao.</summary>
+    private static MediaDisclosure Label => MediaDisclosure.Create("Imagem gerada por IA", "legenda", T0);
+
+    private static MediaJob Pending() => MediaJob.Create(
+        new MediaRequest("catalogo", "um sofa verde", MediaPurpose.CatalogPhoto),
+        new MediaIdempotencyKey("chave"),
+        T0);
+
+    private static MediaJob Generated()
+    {
+        var job = Pending().StartGenerating().Value;
+        return job.MarkGenerated(
+            new MediaHash("abc"),
+            "ab/c/abc.png",
+            new MediaProvenance("openai", "gpt-image-2", "um sofa verde", null, [], "-", null, 0.05m, T0, true))
+            .Value;
+    }
+
+    // ---------------------------------------------------------------------------------
+    // 1. Publish so a partir de Approved
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// O atalho que alguem sempre quer: publicar direto de <c>Generated</c>. Ele nao
+    /// existe, e a mensagem diz por que.
+    /// </summary>
+    [Fact]
+    public void PublishFailsFromGeneratedBecauseNobodyReviewedIt()
+    {
+        var result = Generated().Publish(Label, T0);
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal(MediaErrorCode.InvalidTransition, result.Error!.Code);
+        Assert.Contains("Approved", result.Error.Message, StringComparison.Ordinal);
+    }
+
+    /// <summary>Publish falha a partir de TODO estado que nao seja Approved — nao so de Generated.</summary>
+    [Theory]
+    [InlineData(MediaJobState.Pending)]
+    [InlineData(MediaJobState.Generating)]
+    [InlineData(MediaJobState.Generated)]
+    [InlineData(MediaJobState.Rejected)]
+    [InlineData(MediaJobState.RejectedByPolicy)]
+    [InlineData(MediaJobState.Failed)]
+    public void PublishFailsFromEveryStateThatIsNotApproved(MediaJobState state)
+    {
+        var job = JobIn(state);
+
+        Assert.NotEqual(MediaJobState.Approved, job.State);
+        Assert.False(job.Publish(Label, T0).IsSuccess);
+    }
+
+    /// <summary>E, com a revisao humana no lugar, publica.</summary>
+    [Fact]
+    public void PublishSucceedsFromApproved()
+    {
+        var approved = Generated().Approve(MediaReview.ApprovedBy("lucas", T0)).Value;
+
+        var published = approved.Publish(Label, T0);
+
+        Assert.True(published.IsSuccess);
+        Assert.Equal(MediaJobState.Published, published.Value.State);
+        Assert.Equal(T0, published.Value.PublishedAt);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // 2. Approved so por Approve(revisor)
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>A aprovacao carrega quem e quando — sem isso e um campo booleano.</summary>
+    [Fact]
+    public void ApproveStampsTheReviewerAndTheTime()
+    {
+        var approved = Generated().Approve(MediaReview.ApprovedBy("lucas", T0, "cor confere")).Value;
+
+        Assert.Equal(MediaJobState.Approved, approved.State);
+        Assert.Equal("lucas", approved.Review!.Reviewer);
+        Assert.Equal(T0, approved.Review.DecidedAt);
+        Assert.Equal("cor confere", approved.Review.Note);
+    }
+
+    /// <summary>Revisor em branco nao carimba nada, e a recusa e na construcao da revisao.</summary>
+    [Fact]
+    public void AnAnonymousReviewIsRefusedAtConstruction()
+        => Assert.Throws<ArgumentException>(() => MediaReview.ApprovedBy("   ", T0));
+
+    /// <summary>
+    /// Aprovar com um veredito de REJEICAO seria registrar o oposto do que o humano
+    /// decidiu. O tipo recusa.
+    /// </summary>
+    [Fact]
+    public void ApproveRefusesAReviewThatSaysRejected()
+    {
+        var result = Generated().Approve(MediaReview.RejectedBy("lucas", T0));
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal(MediaErrorCode.InvalidTransition, result.Error!.Code);
+    }
+
+    /// <summary>Aprovar antes de existirem bytes nao e transicao.</summary>
+    [Fact]
+    public void ApproveFailsBeforeTheBytesExist()
+        => Assert.False(Pending().Approve(MediaReview.ApprovedBy("lucas", T0)).IsSuccess);
+
+    // ---------------------------------------------------------------------------------
+    // 3. RejectedByPolicy nao e retryable; Failed e
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// A distincao que vale dinheiro. Bloqueio de moderacao e resposta definitiva; erro
+    /// tecnico e tentativa perdida.
+    /// </summary>
+    [Fact]
+    public void PolicyBlockIsTerminalAndTechnicalFailureIsNot()
+    {
+        var blocked = Pending().StartGenerating().Value.RejectByPolicy("moderacao").Value;
+        var failed = Pending().StartGenerating().Value.Fail("HTTP 503").Value;
+
+        Assert.Equal(MediaJobState.RejectedByPolicy, blocked.State);
+        Assert.False(blocked.IsRetryable);
+        Assert.False(blocked.StartGenerating().IsSuccess);
+
+        Assert.Equal(MediaJobState.Failed, failed.State);
+        Assert.True(failed.IsRetryable);
+        Assert.True(failed.StartGenerating().IsSuccess);
+    }
+
+    /// <summary>Um job em <c>Generated</c> carrega hash, caminho e proveniencia — os tres juntos.</summary>
+    [Fact]
+    public void GeneratedCarriesHashPathAndProvenanceTogether()
+    {
+        var job = Generated();
+
+        Assert.Equal(MediaJobState.Generated, job.State);
+        Assert.Equal("abc", job.Hash!.Value.Value);
+        Assert.Equal("ab/c/abc.png", job.RelativePath);
+        Assert.Equal("gpt-image-2", job.Provenance!.ModelId);
+    }
+
+    /// <summary>Uma transicao recusada NAO muda o job: o registro e imutavel.</summary>
+    [Fact]
+    public void ARefusedTransitionLeavesTheJobUntouched()
+    {
+        var job = Generated();
+
+        _ = job.Publish(Label, T0);
+
+        Assert.Equal(MediaJobState.Generated, job.State);
+        Assert.Null(job.PublishedAt);
+    }
+
+    private static MediaJob JobIn(MediaJobState state) => state switch
+    {
+        MediaJobState.Pending => Pending(),
+        MediaJobState.Generating => Pending().StartGenerating().Value,
+        MediaJobState.Generated => Generated(),
+        MediaJobState.Approved => Generated().Approve(MediaReview.ApprovedBy("lucas", T0)).Value,
+        MediaJobState.Rejected => Generated().Reject(MediaReview.RejectedBy("lucas", T0)).Value,
+        MediaJobState.RejectedByPolicy => Pending().StartGenerating().Value.RejectByPolicy("moderacao").Value,
+        MediaJobState.Failed => Pending().StartGenerating().Value.Fail("HTTP 503").Value,
+        _ => throw new ArgumentOutOfRangeException(nameof(state)),
+    };
+}

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/MediaReviewTests.cs

@@ -0,0 +1,89 @@
+using Morph.AiKit.Media;
+using Xunit;
+
+namespace Morph.AiKit.Tests;
+
+/// <summary>
+/// Canarios de <see cref="MediaReview"/>.
+/// </summary>
+/// <remarks>
+/// A afirmacao que este arquivo protege nao e "aprovar funciona" — e que
+/// <see cref="MediaReview"/> <b>delega</b> ao <see cref="MediaJob"/> em vez de reimplementar
+/// a regra. Uma segunda copia de "so Approved publica" e exatamente como as duas divergem, e
+/// e o padrao de falha que esta epic catalogou sete vezes: o teste mede uma COPIA do objeto.
+/// </remarks>
+public sealed class MediaReviewTests
+{
+    private static readonly DateTimeOffset T0 = new(2026, 9, 8, 12, 0, 0, TimeSpan.Zero);
+
+    private static MediaDisclosure Label => MediaDisclosure.Create("Imagem gerada por IA", "legenda", T0);
+
+    private static MediaJob Generated()
+    {
+        var job = MediaJob.Create(
+            new MediaRequest("catalogo", "um sofa verde", MediaPurpose.CatalogPhoto),
+            new MediaIdempotencyKey("chave"),
+            T0).StartGenerating().Value;
+
+        return job.MarkGenerated(
+            new MediaHash("abc"),
+            "ab/c/abc.png",
+            new MediaProvenance("openai", "gpt-image-2", "p", null, [], "-", null, 0m, T0, true)).Value;
+    }
+
+    /// <summary>O atalho aprova e carimba.</summary>
+    [Fact]
+    public void ApproveDelegatesAndStamps()
+    {
+        var result = MediaReview.Approve(Generated(), "lucas", T0, "ok");
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal(MediaJobState.Approved, result.Value.State);
+        Assert.Equal("lucas", result.Value.Review!.Reviewer);
+    }
+
+    /// <summary>Rejeitar e terminal e tambem carimba.</summary>
+    [Fact]
+    public void RejectDelegatesAndStamps()
+    {
+        var result = MediaReview.Reject(Generated(), "lucas", T0, "cor errada");
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal(MediaJobState.Rejected, result.Value.State);
+        Assert.Equal(MediaReviewDecision.Rejected, result.Value.Review!.Decision);
+    }
+
+    /// <summary>
+    /// O atalho de publicar NAO tem uma regra propria: ele recusa exatamente onde
+    /// <see cref="MediaJob.Publish"/> recusa. Confere-se comparando as DUAS chamadas sobre o
+    /// MESMO job — se <c>MediaReview</c> tivesse copiado a regra, aqui e onde a copia
+    /// divergiria.
+    /// </summary>
+    [Fact]
+    public void PublishThroughTheReviewFacadeAgreesWithTheJobItself()
+    {
+        var generated = Generated();
+        var approved = generated.Approve(MediaReview.ApprovedBy("lucas", T0)).Value;
+
+        Assert.Equal(generated.Publish(Label, T0).IsSuccess, MediaReview.Publish(generated, Label, T0).IsSuccess);
+        Assert.Equal(approved.Publish(Label, T0).IsSuccess, MediaReview.Publish(approved, Label, T0).IsSuccess);
+
+        Assert.False(MediaReview.Publish(generated, Label, T0).IsSuccess);
+        Assert.True(MediaReview.Publish(approved, Label, T0).IsSuccess);
+    }
+
+    /// <summary>Job nulo e falha de composicao, nao Result: quem chama errou o codigo.</summary>
+    [Fact]
+    public void ANullJobIsAProgrammingError()
+        => Assert.Throws<ArgumentNullException>(() => MediaReview.Approve(null!, "lucas", T0));
+
+    /// <summary>Um juiz LLM cabe na nota, nunca no campo do revisor de uma foto de catalogo.</summary>
+    [Fact]
+    public void TheNoteCarriesThePreFilterVerdict()
+    {
+        var review = MediaReview.ApprovedBy("lucas", T0, "juiz LLM: 8/10 em fidelidade de cor");
+
+        Assert.Equal("lucas", review.Reviewer);
+        Assert.Contains("juiz LLM", review.Note, StringComparison.Ordinal);
+    }
+}