@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

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

@@ -0,0 +1,47 @@
+namespace Morph.AiKit.Media;
+
+/// <summary>
+/// Os oito estados de um job de midia.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A distincao que vale dinheiro esta entre <see cref="Failed"/> e
+/// <see cref="RejectedByPolicy"/>. Um bloqueio de moderacao e uma resposta DEFINITIVA:
+/// retenta-lo gasta para receber o mesmo "nao" — e no provider que cobra o bloqueio, gasta
+/// duas vezes. Modelar bloqueio como erro tecnico e como um laco de retry vira uma fatura.
+/// </para>
+/// <para>
+/// A distincao que vale credibilidade esta entre <see cref="Generated"/> e
+/// <see cref="Approved"/>: <c>Approved</c> so existe por uma transicao que carimba um
+/// revisor humano, e <c>Published</c> so existe a partir de <c>Approved</c>.
+/// </para>
+/// </remarks>
+public enum MediaJobState
+{
+    /// <summary>Pedido aceito. Nada foi gasto ainda.</summary>
+    Pending = 0,
+
+    /// <summary>Chamada paga em voo, ou tarefa remota em polling.</summary>
+    Generating = 1,
+
+    /// <summary>Os bytes existem NO SEU storage. Nao basta a tarefa remota ter concluido.</summary>
+    Generated = 2,
+
+    /// <summary>Um humano aprovou, com nome e carimbo de tempo. Unica porta para <see cref="Published"/>.</summary>
+    Approved = 3,
+
+    /// <summary>Um humano recusou. Terminal.</summary>
+    Rejected = 4,
+
+    /// <summary>Bloqueio de moderacao do provider. Terminal e <b>nao</b> retryable.</summary>
+    RejectedByPolicy = 5,
+
+    /// <summary>
+    /// Publicado. So se alcanca por <see cref="MediaJob.Publish"/>, que exige finalidade
+    /// publicavel e — quando a finalidade a pede — uma <see cref="MediaDisclosure"/> registrada.
+    /// </summary>
+    Published = 6,
+
+    /// <summary>Erro tecnico (429, 5xx, timeout, download quebrado). Retryable.</summary>
+    Failed = 7,
+}

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

@@ -0,0 +1,102 @@
+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;
+    private readonly decimal _medium;
+    private readonly decimal _high;
+    private readonly decimal _perSecond;
+
+    private MediaPricing(MediaKind kind, decimal low, decimal medium, decimal high, decimal perSecond)
+    {
+        Kind = kind;
+        _low = low;
+        _medium = medium;
+        _high = high;
+        _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);
+        ArgumentOutOfRangeException.ThrowIfNegative(medium);
+        ArgumentOutOfRangeException.ThrowIfNegative(high);
+
+        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);
+
+        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);
+
+        if (request.Kind != Kind)
+        {
+            return MediaResult<decimal>.Fail(
+                MediaErrorCode.PricingMissing,
+                $"tarifa de {Kind} aplicada a um pedido de {request.Kind}: a unidade de cobranca e outra.");
+        }
+
+        if (Kind == MediaKind.Image)
+        {
+            var unit = (request.Options.Quality ?? MediaQuality.Low) switch
+            {
+                MediaQuality.High => _high,
+                MediaQuality.Medium => _medium,
+                _ => _low,
+            };
+
+            return MediaResult<decimal>.Ok(unit * Math.Max(1, request.Options.Count ?? 1));
+        }
+
+        if (request.Options.DurationSeconds is not { } seconds)
+        {
+            return MediaResult<decimal>.Fail(
+                MediaErrorCode.PricingMissing,
+                "pedido de video sem durationSeconds: video cobra por segundo, e arbitrar segundos e arbitrar dinheiro.");
+        }
+
+        return MediaResult<decimal>.Ok(_perSecond * seconds * Math.Max(1, request.Options.Count ?? 1));
+    }
+}

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

@@ -0,0 +1,44 @@
+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,
+    string PromptFinal,
+    string? RevisedPrompt,
+    IReadOnlyList<string> RefsHash,
+    string Options,
+    string? ResponseId,
+    decimal EstimatedCostUsd,
+    DateTimeOffset CreatedAt,
+    bool C2paPreserved);

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

@@ -0,0 +1,192 @@
+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);
+        ArgumentException.ThrowIfNullOrWhiteSpace(mediaType);
+
+        Name = name;
+        MediaType = mediaType;
+        Bytes = bytes;
+        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>
+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>
+    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>
+    public string ToCanonicalString()
+        => string.Join('|',
+            $"quality={Quality?.ToString() ?? "-"}",
+            $"count={Count?.ToString() ?? "-"}",
+            $"w={Width?.ToString() ?? "-"}",
+            $"h={Height?.ToString() ?? "-"}",
+            $"mime={MediaType ?? "-"}",
+            $"dur={DurationSeconds?.ToString() ?? "-"}",
+            $"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))
+        {
+            return MediaResult<MediaRequest>.Fail(
+                MediaErrorCode.InvalidRequest, "alias vazio: o pedido nao sabe a que modelo ir.");
+        }
+
+        if (string.IsNullOrWhiteSpace(Prompt))
+        {
+            return MediaResult<MediaRequest>.Fail(
+                MediaErrorCode.InvalidRequest, "prompt vazio: nao ha o que gerar.");
+        }
+
+        if (Options.Count is { } count && count <= 0)
+        {
+            return MediaResult<MediaRequest>.Fail(
+                MediaErrorCode.InvalidRequest, $"count={count}: pedir zero candidatas nao e um pedido.");
+        }
+
+        if (Kind == MediaKind.Video && Options.DurationSeconds is { } seconds && seconds <= 0)
+        {
+            return MediaResult<MediaRequest>.Fail(
+                MediaErrorCode.InvalidRequest, $"durationSeconds={seconds}: video de duracao nao positiva.");
+        }
+
+        return MediaResult<MediaRequest>.Ok(this);
+    }
+}

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

@@ -0,0 +1,94 @@
+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;
+
+    private MediaResult(bool isSuccess, T value, MediaError? error)
+    {
+        IsSuccess = isSuccess;
+        _value = value;
+        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)
+            : throw new InvalidOperationException("FailLike sobre um Result de sucesso.");
+}

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

@@ -0,0 +1,99 @@
+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)
+    {
+        Reviewer = reviewer;
+        Decision = decision;
+        DecidedAt = decidedAt;
+        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,
+        DateTimeOffset publishedAt)
+    {
+        ArgumentNullException.ThrowIfNull(job);
+        return job.Publish(disclosure, publishedAt);
+    }
+}