@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

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

@@ -0,0 +1,253 @@
+using Morph.AiKit.Media.Providers;
+
+namespace Morph.AiKit.Media;
+
+/// <summary>
+/// A implementacao de <see cref="IMediaGenerator"/>. <b><c>internal</c></b>: o projeto
+/// enxerga a interface, nunca o tipo.
+/// </summary>
+/// <remarks>
+/// A ORDEM do <see cref="EnqueueAsync"/> e o contrato, e ela e economia, nao estilo:
+/// validar, resolver alias, derivar a chave de PEDIDO, <b>consultar a chave antes de
+/// qualquer coisa paga</b>, so entao estimar custo e reservar teto, e por ultimo gravar o
+/// job. Um retry que chega aqui reencontra o job e nao paga de novo; um estouro de teto
+/// recusa antes de o dinheiro sair.
+/// </remarks>
+internal sealed class MediaGenerator : IMediaGenerator
+{
+    private readonly IMediaAliasResolver _aliases;
+    private readonly IMediaJobRepository _jobs;
+    private readonly IMediaBudget? _budget;
+    private readonly IMediaClock _clock;
+
+    public MediaGenerator(
+        IMediaAliasResolver aliases,
+        IMediaJobRepository jobs,
+        IMediaBudget? budget,
+        IMediaClock clock)
+    {
+        ArgumentNullException.ThrowIfNull(aliases);
+        ArgumentNullException.ThrowIfNull(jobs);
+        ArgumentNullException.ThrowIfNull(clock);
+
+        _aliases = aliases;
+        _jobs = jobs;
+        _budget = budget;
+        _clock = clock;
+    }
+
+    /// <inheritdoc />
+    public async Task<MediaResult<MediaJobId>> EnqueueAsync(
+        MediaRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        var valid = request.Validate();
+        if (!valid.IsSuccess)
+        {
+            return MediaResult<MediaJobId>.FailLike(valid);
+        }
+
+        var binding = _aliases.Resolve(request.Alias);
+        if (!binding.IsSuccess)
+        {
+            return MediaResult<MediaJobId>.FailLike(binding);
+        }
+
+        if (binding.Value.Kind != request.Kind)
+        {
+            return MediaResult<MediaJobId>.Fail(
+                MediaErrorCode.InvalidRequest,
+                $"alias '{request.Alias}' produz {binding.Value.Kind}, e o pedido e de {request.Kind}.");
+        }
+
+        var key = MediaIdempotencyKey.From(request, binding.Value.Provider, binding.Value.Model);
+
+        // ANTES de qualquer coisa paga. Um pedido identico a outro ja atendido reusa o job
+        // existente; so um job em Failed vale outra tentativa.
+        var existing = await _jobs.FindByIdempotencyKeyAsync(key, cancellationToken).ConfigureAwait(false);
+        if (existing is not null && existing.State != MediaJobState.Failed)
+        {
+            return MediaResult<MediaJobId>.Ok(existing.Id);
+        }
+
+        var estimate = binding.Value.Pricing.EstimateUsd(request);
+        if (!estimate.IsSuccess)
+        {
+            return MediaResult<MediaJobId>.FailLike(estimate);
+        }
+
+        if (_budget is not null)
+        {
+            var reserved = await _budget
+                .TryReserveAsync(request, estimate.Value, cancellationToken)
+                .ConfigureAwait(false);
+
+            if (!reserved)
+            {
+                return MediaResult<MediaJobId>.Fail(
+                    MediaErrorCode.BudgetExceeded,
+                    $"alias '{request.Alias}': o custo estimado de {estimate.Value:F4} USD estoura o teto. " +
+                    "A recusa e no enqueue de proposito — depois da chamada, o dinheiro ja saiu.");
+            }
+        }
+
+        var job = MediaJob.Create(request, key, _clock.UtcNow);
+        await _jobs.SaveAsync(job, cancellationToken).ConfigureAwait(false);
+
+        return MediaResult<MediaJobId>.Ok(job.Id);
+    }
+
+    /// <inheritdoc />
+    public async Task<MediaResult<MediaJob>> GetAsync(MediaJobId id, CancellationToken cancellationToken = default)
+    {
+        var job = await _jobs.FindAsync(id, cancellationToken).ConfigureAwait(false);
+
+        return job is null
+            ? MediaResult<MediaJob>.Fail(MediaErrorCode.NotFound, $"job {id} nao existe.")
+            : MediaResult<MediaJob>.Ok(job);
+    }
+}
+
+/// <summary>
+/// Executa um job: chama o provider, guarda os bytes, move o estado. <b><c>internal</c></b>
+/// — e este e o unico tipo do subsistema que segura um <see cref="IMediaProvider"/>.
+/// </summary>
+/// <remarks>
+/// A ordem tambem e o contrato: <c>Generating</c> antes da chamada (para que um worker
+/// morto no meio deixe rastro), os bytes GRAVADOS antes de <c>Generated</c> (um job em
+/// <c>Generated</c> sem bytes no storage mente sobre o proprio estado), e o bloqueio de
+/// moderacao indo para <c>RejectedByPolicy</c> e nao para <c>Failed</c>.
+/// </remarks>
+internal sealed class MediaWorker : IMediaJobRunner
+{
+    private readonly IMediaAliasResolver _aliases;
+    private readonly IMediaJobRepository _jobs;
+    private readonly IMediaStore _store;
+    private readonly IReadOnlyList<IMediaProvider> _providers;
+    private readonly IMediaClock _clock;
+
+    public MediaWorker(
+        IMediaAliasResolver aliases,
+        IMediaJobRepository jobs,
+        IMediaStore store,
+        IReadOnlyList<IMediaProvider> providers,
+        IMediaClock clock)
+    {
+        ArgumentNullException.ThrowIfNull(aliases);
+        ArgumentNullException.ThrowIfNull(jobs);
+        ArgumentNullException.ThrowIfNull(store);
+        ArgumentNullException.ThrowIfNull(providers);
+        ArgumentNullException.ThrowIfNull(clock);
+
+        _aliases = aliases;
+        _jobs = jobs;
+        _store = store;
+        _providers = providers;
+        _clock = clock;
+    }
+
+    /// <inheritdoc />
+    public async Task<MediaResult<MediaJob>> RunAsync(MediaJobId id, CancellationToken cancellationToken = default)
+    {
+        var job = await _jobs.FindAsync(id, cancellationToken).ConfigureAwait(false);
+        if (job is null)
+        {
+            return MediaResult<MediaJob>.Fail(MediaErrorCode.NotFound, $"job {id} nao existe.");
+        }
+
+        var binding = _aliases.Resolve(job.Request.Alias);
+        if (!binding.IsSuccess)
+        {
+            return await PersistAsync(job.Fail(binding.Error!.Message), cancellationToken).ConfigureAwait(false);
+        }
+
+        var provider = _providers.FirstOrDefault(p =>
+            p.Provider == binding.Value.Provider && p.Supports(job.Request.Kind));
+
+        if (provider is null)
+        {
+            return await PersistAsync(
+                job.Fail($"nenhum adaptador atende provider '{binding.Value.Provider}' para {job.Request.Kind}."),
+                cancellationToken).ConfigureAwait(false);
+        }
+
+        var generating = job.StartGenerating();
+        if (!generating.IsSuccess)
+        {
+            return generating;
+        }
+
+        job = generating.Value;
+        await _jobs.SaveAsync(job, cancellationToken).ConfigureAwait(false);
+
+        var produced = await provider.ProduceAsync(job.Request, binding.Value, cancellationToken).ConfigureAwait(false);
+
+        if (!produced.IsSuccess)
+        {
+            // A distincao que vale dinheiro: bloqueio de politica e terminal, falha tecnica
+            // e retryable. Colapsar as duas em "erro" e como um laco de retry vira fatura.
+            var transition = produced.Error!.Code == MediaErrorCode.PolicyBlocked
+                ? job.RejectByPolicy(produced.Error.Message)
+                : job.Fail(produced.Error.Message);
+
+            return await PersistAsync(transition, cancellationToken).ConfigureAwait(false);
+        }
+
+        var artifact = produced.Value;
+        var entry = await _store
+            .PutAsync(artifact.Bytes, artifact.MediaType, cancellationToken)
+            .ConfigureAwait(false);
+
+        var estimate = binding.Value.Pricing.EstimateUsd(job.Request);
+
+        var provenance = new MediaProvenance(
+            binding.Value.Provider,
+            binding.Value.Model,
+            job.Request.Prompt,
+            artifact.RevisedPrompt,
+            [.. job.Request.References.Select(r => r.Sha256Hex)],
+            job.Request.Options.ToCanonicalString(),
+            artifact.ResponseId,
+            estimate.IsSuccess ? estimate.Value : 0m,
+            _clock.UtcNow,
+            artifact.C2paPreserved);
+
+        return await PersistAsync(
+            job.MarkGenerated(entry.Hash, entry.RelativePath, provenance),
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    private async Task<MediaResult<MediaJob>> PersistAsync(
+        MediaResult<MediaJob> transition,
+        CancellationToken cancellationToken)
+    {
+        if (transition.IsSuccess)
+        {
+            await _jobs.SaveAsync(transition.Value, cancellationToken).ConfigureAwait(false);
+        }
+
+        return transition;
+    }
+}
+
+/// <summary>
+/// Monta os adaptadores de provider. <b><c>internal</c></b>, e e por isso que nao existe
+/// caminho publico ate um <see cref="IMediaProvider"/>.
+/// </summary>
+internal static class MediaProviderCatalog
+{
+    /// <summary>Os tres adaptadores que o kit traz.</summary>
+    public static IReadOnlyList<IMediaProvider> Build(IMediaClientFactory clients)
+    {
+        ArgumentNullException.ThrowIfNull(clients);
+
+        return
+        [
+            new OpenAIImageProvider(clients),
+            new GoogleImageProvider(clients),
+            new VeoVideoProvider(clients),
+        ];
+    }
+}

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

@@ -0,0 +1,103 @@
+using System.Security.Cryptography;
+using System.Text;
+
+namespace Morph.AiKit.Media;
+
+/// <summary>
+/// A chave de idempotencia do <b>PEDIDO</b> — a que dedupe a CHAMADA PAGA.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Ela nao e o <see cref="MediaHash"/>, e a diferenca e o defeito caro deste
+/// subsistema.</b> Esta chave e o sha256 do PEDIDO (provider + modelo + prompt normalizado
+/// + sha256 de cada referencia + opcoes) e responde "ja pagamos por isto?". O
+/// <see cref="MediaHash"/> e o sha256 dos BYTES e responde "ja guardamos isto?". Duas
+/// perguntas diferentes: dois pedidos distintos podem produzir bytes identicos, e o mesmo
+/// pedido sempre produz o mesmo pedido.
+/// </para>
+/// <para>
+/// Ela e consultada <b>antes</b> de chamar o provider. E o que faz um retry — de fila, de
+/// worker reiniciado, de webhook duplicado — custar zero.
+/// </para>
+/// <para>
+/// <b>O prompt e normalizado, nao minusculado.</b> Espacos em branco colapsam e as pontas
+/// sao aparadas, porque um espaco a mais nao muda o pedido; a caixa e preservada, porque
+/// num prompt ela muda (nomes de marca, texto literal entre aspas que vai aparecer na
+/// imagem).
+/// </para>
+/// </remarks>
+/// <param name="Value">sha256 em hex minusculo.</param>
+public readonly record struct MediaIdempotencyKey(string Value)
+{
+    /// <summary>Separador de CAMPO na forma canonica: UNIT SEPARATOR (U+001F).</summary>
+    /// <remarks>
+    /// Um caractere de controle, e nao <c>|</c> ou <c>:</c>, porque o separador nao pode
+    /// aparecer dentro de um campo. Um prompt que contivesse o separador emendaria dois
+    /// campos numa chave so, e duas requisicoes diferentes passariam a compartilhar a
+    /// chave — o que faz uma reusar o artefato PAGO da outra. Pior que pagar duas vezes.
+    /// Escrito como <c>(char)0x1F</c> e nao como o caractere cru: um byte de controle
+    /// invisivel no fonte e uma armadilha para o proximo editor.
+    /// </remarks>
+    private const char FieldSeparator = (char)0x1F;
+
+    /// <summary>Separador de ITEM dentro de um campo: RECORD SEPARATOR (U+001E).</summary>
+    private const char ItemSeparator = (char)0x1E;
+
+    /// <summary>
+    /// Deriva a chave do pedido resolvido.
+    /// </summary>
+    /// <param name="request">O pedido.</param>
+    /// <param name="provider">A familia do SDK que vai atender (<c>openai</c>, <c>google</c>).</param>
+    /// <param name="model">O modelo resolvido pelo alias — nunca o alias, que pode ser repontado.</param>
+    /// <exception cref="ArgumentNullException">Pedido nulo.</exception>
+    public static MediaIdempotencyKey From(MediaRequest request, string provider, string model)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ArgumentException.ThrowIfNullOrWhiteSpace(provider);
+        ArgumentException.ThrowIfNullOrWhiteSpace(model);
+
+        var canonical = new StringBuilder()
+            .Append(provider).Append(FieldSeparator)
+            .Append(model).Append(FieldSeparator)
+            .Append(request.Kind).Append(FieldSeparator)
+            .Append(NormalizePrompt(request.Prompt)).Append(FieldSeparator)
+            .Append(string.Join(ItemSeparator, request.References.Select(r => r.Sha256Hex)))
+            .Append(FieldSeparator)
+            .Append(request.Options.ToCanonicalString())
+            .ToString();
+
+        return new MediaIdempotencyKey(
+            Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(canonical))));
+    }
+
+    /// <summary>Apara as pontas e colapsa espacos em branco. NAO minuscula.</summary>
+    public static string NormalizePrompt(string prompt)
+    {
+        ArgumentNullException.ThrowIfNull(prompt);
+
+        var builder = new StringBuilder(prompt.Length);
+        var pendingSpace = false;
+
+        foreach (var ch in prompt)
+        {
+            if (char.IsWhiteSpace(ch))
+            {
+                pendingSpace = builder.Length > 0;
+                continue;
+            }
+
+            if (pendingSpace)
+            {
+                builder.Append(' ');
+                pendingSpace = false;
+            }
+
+            builder.Append(ch);
+        }
+
+        return builder.ToString();
+    }
+
+    /// <summary>A chave, para log.</summary>
+    public override string ToString() => Value;
+}

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

@@ -0,0 +1,259 @@
+namespace Morph.AiKit.Media;
+
+/// <summary>
+/// Um pedido de midia com estado. <b>E o unico objeto de dominio que a superficie publica
+/// devolve</b> — nunca bytes.
+/// </summary>
+/// <remarks>
+/// <para>
+/// As transicoes sao metodos que devolvem <see cref="MediaResult{T}"/> e um job NOVO: o
+/// registro e imutavel, e uma transicao invalida e informacao devolvida, nunca excecao.
+/// </para>
+/// <para>
+/// <b>Duas invariantes carregam o standard inteiro:</b>
+/// </para>
+/// <list type="number">
+///   <item>
+///     <see cref="Approve"/> e a UNICA porta para <see cref="MediaJobState.Approved"/>, e
+///     ela exige um revisor com nome e carimbo de tempo. E assim que "ha revisao humana"
+///     deixa de ser uma frase no README e vira um caminho que o codigo nao tem.
+///   </item>
+///   <item>
+///     <see cref="Publish"/> falha a partir de qualquer estado que nao seja
+///     <c>Approved</c>. Nao ha atalho, nem flag, nem sobrecarga "force".
+///   </item>
+/// </list>
+/// <para>
+/// E ha uma terceira, que vale dinheiro: <see cref="RejectByPolicy"/> produz um estado
+/// terminal com <see cref="IsRetryable"/> falso. Bloqueio de moderacao nao e erro tecnico —
+/// retenta-lo gasta para receber o mesmo "nao".
+/// </para>
+/// </remarks>
+public sealed record MediaJob
+{
+    private MediaJob(MediaJobId id, MediaRequest request, MediaIdempotencyKey key, DateTimeOffset createdAt)
+    {
+        Id = id;
+        Request = request;
+        IdempotencyKey = key;
+        CreatedAt = createdAt;
+        State = MediaJobState.Pending;
+    }
+
+    /// <summary>A identidade. O unico valor que sai pela superficie publica.</summary>
+    public MediaJobId Id { get; private init; }
+
+    /// <summary>O pedido, congelado.</summary>
+    public MediaRequest Request { get; private init; }
+
+    /// <summary>A chave que dedupe a chamada paga.</summary>
+    public MediaIdempotencyKey IdempotencyKey { get; private init; }
+
+    /// <summary>Onde o job esta.</summary>
+    public MediaJobState State { get; private init; }
+
+    /// <summary>Quando o pedido foi aceito.</summary>
+    public DateTimeOffset CreatedAt { get; private init; }
+
+    /// <summary>sha256 dos bytes, a partir de <see cref="MediaJobState.Generated"/>.</summary>
+    public MediaHash? Hash { get; private init; }
+
+    /// <summary>Caminho RELATIVO no blob do projeto. Nunca URL de provider.</summary>
+    public string? RelativePath { get; private init; }
+
+    /// <summary>A proveniencia, gravada na geracao.</summary>
+    public MediaProvenance? Provenance { get; private init; }
+
+    /// <summary>Quem decidiu, quando, e o que escreveu. Nulo enquanto ninguem revisou.</summary>
+    public MediaReview? Review { get; private init; }
+
+    /// <summary>Por que falhou ou foi bloqueado. Nulo nos estados saudaveis.</summary>
+    public string? FailureReason { get; private init; }
+
+    /// <summary>Quando foi publicado.</summary>
+    public DateTimeOffset? PublishedAt { get; private init; }
+
+    /// <summary>
+    /// A marcação "gerado por IA" registrada na publicação, ou nulo quando a finalidade não
+    /// a exige. Ver <see cref="MediaDisclosure"/> e <see cref="Publish"/>.
+    /// </summary>
+    public MediaDisclosure? Disclosure { get; private init; }
+
+    /// <summary>
+    /// Se vale tentar de novo. <b>So <see cref="MediaJobState.Failed"/> e retryable.</b>
+    /// <see cref="MediaJobState.RejectedByPolicy"/> nao e, e essa e a diferenca que impede
+    /// um laco de retry de virar uma fatura.
+    /// </summary>
+    public bool IsRetryable => State == MediaJobState.Failed;
+
+    /// <summary>Nasce em <see cref="MediaJobState.Pending"/>. Nada foi gasto ainda.</summary>
+    /// <exception cref="ArgumentNullException">Pedido nulo.</exception>
+    public static MediaJob Create(MediaRequest request, MediaIdempotencyKey key, DateTimeOffset createdAt)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        return new MediaJob(MediaJobId.New(), request, key, createdAt);
+    }
+
+    /// <summary>Pending para Generating: a chamada paga esta em voo.</summary>
+    public MediaResult<MediaJob> StartGenerating()
+        => State == MediaJobState.Pending || State == MediaJobState.Failed
+            ? MediaResult<MediaJob>.Ok(this with { State = MediaJobState.Generating, FailureReason = null })
+            : Invalid(nameof(StartGenerating), MediaJobState.Generating);
+
+    /// <summary>
+    /// Generating para Generated. Exige hash, caminho e proveniencia <b>juntos</b>: um job
+    /// em <c>Generated</c> sem bytes no seu storage esta mentindo sobre o proprio estado.
+    /// </summary>
+    public MediaResult<MediaJob> MarkGenerated(MediaHash hash, string relativePath, MediaProvenance provenance)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(relativePath);
+        ArgumentNullException.ThrowIfNull(provenance);
+
+        return State == MediaJobState.Generating
+            ? MediaResult<MediaJob>.Ok(this with
+            {
+                State = MediaJobState.Generated,
+                Hash = hash,
+                RelativePath = relativePath,
+                Provenance = provenance,
+            })
+            : Invalid(nameof(MarkGenerated), MediaJobState.Generated);
+    }
+
+    /// <summary>Falha tecnica. Retryable.</summary>
+    public MediaResult<MediaJob> Fail(string reason)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(reason);
+
+        return State is MediaJobState.Pending or MediaJobState.Generating
+            ? MediaResult<MediaJob>.Ok(this with { State = MediaJobState.Failed, FailureReason = reason })
+            : Invalid(nameof(Fail), MediaJobState.Failed);
+    }
+
+    /// <summary>
+    /// Bloqueio de moderacao. Terminal e NAO retryable — ver <see cref="IsRetryable"/>.
+    /// </summary>
+    public MediaResult<MediaJob> RejectByPolicy(string reason)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(reason);
+
+        return State is MediaJobState.Pending or MediaJobState.Generating or MediaJobState.Generated
+            ? MediaResult<MediaJob>.Ok(this with
+            {
+                State = MediaJobState.RejectedByPolicy,
+                FailureReason = reason,
+            })
+            : Invalid(nameof(RejectByPolicy), MediaJobState.RejectedByPolicy);
+    }
+
+    /// <summary>
+    /// A UNICA porta para <see cref="MediaJobState.Approved"/>, e ela exige um humano
+    /// nomeado com carimbo de tempo.
+    /// </summary>
+    public MediaResult<MediaJob> Approve(MediaReview review)
+    {
+        ArgumentNullException.ThrowIfNull(review);
+
+        if (review.Decision != MediaReviewDecision.Approved)
+        {
+            return MediaResult<MediaJob>.Fail(
+                MediaErrorCode.InvalidTransition,
+                $"job {Id}: Approve recebeu uma revisao com decisao '{review.Decision}'. " +
+                "Aprovar com um veredito de rejeicao seria registrar o oposto do que o humano decidiu.");
+        }
+
+        return State == MediaJobState.Generated
+            ? MediaResult<MediaJob>.Ok(this with { State = MediaJobState.Approved, Review = review })
+            : Invalid(nameof(Approve), MediaJobState.Approved);
+    }
+
+    /// <summary>Recusa humana. Terminal.</summary>
+    public MediaResult<MediaJob> Reject(MediaReview review)
+    {
+        ArgumentNullException.ThrowIfNull(review);
+
+        if (review.Decision != MediaReviewDecision.Rejected)
+        {
+            return MediaResult<MediaJob>.Fail(
+                MediaErrorCode.InvalidTransition,
+                $"job {Id}: Reject recebeu uma revisao com decisao '{review.Decision}'.");
+        }
+
+        return State == MediaJobState.Generated
+            ? MediaResult<MediaJob>.Ok(this with { State = MediaJobState.Rejected, Review = review })
+            : Invalid(nameof(Reject), MediaJobState.Rejected);
+    }
+
+    /// <summary>
+    /// Publica. <b>Tres portas, e cada uma fecha um caminho que existia so na prosa:</b>
+    /// </summary>
+    /// <remarks>
+    /// <list type="number">
+    ///   <item>
+    ///     Falha a partir de qualquer estado que nao seja <see cref="MediaJobState.Approved"/>
+    ///     — inclusive de <c>Generated</c>, que e o atalho que alguem sempre quer. E o que
+    ///     torna a REVISAO HUMANA um caminho que o codigo nao tem.
+    ///   </item>
+    ///   <item>
+    ///     Falha quando a finalidade nao e publicavel. <see cref="MediaPurpose.Draft"/> se
+    ///     declarava "nunca publicavel" num comentario XML que nada cobrava.
+    ///   </item>
+    ///   <item>
+    ///     Falha quando a finalidade exige MARCACAO e ela nao foi passada. Era a unica das
+    ///     quatro afirmacoes da rubrica <c>media-claims</c> presa por prosa — e e a que
+    ///     carrega a obrigacao legal (AI Act art. 50).
+    ///   </item>
+    /// </list>
+    /// <para>
+    /// O que isto prova e o que nao prova esta escrito em <see cref="MediaDisclosure"/>: o
+    /// kit garante que a DECISAO foi tomada e gravada, nao que o rotulo chegou aos olhos de
+    /// alguem — a renderizacao e do aplicativo consumidor.
+    /// </para>
+    /// </remarks>
+    /// <param name="disclosure">
+    /// A marcacao. Pode ser nula somente quando <see cref="MediaPurpose.RequiresDisclosure"/>
+    /// e falso para a finalidade do pedido.
+    /// </param>
+    /// <param name="publishedAt">Quando.</param>
+    public MediaResult<MediaJob> Publish(MediaDisclosure? disclosure, DateTimeOffset publishedAt)
+    {
+        if (State != MediaJobState.Approved)
+        {
+            return MediaResult<MediaJob>.Fail(
+                MediaErrorCode.InvalidTransition,
+                $"job {Id}: Publish a partir de '{State}'. So um job Approved pode ser publicado, e " +
+                "Approved so existe por Approve(revisor). Publicar sem revisao humana e o defeito que " +
+                "esta maquina de estados existe para impedir.");
+        }
+
+        if (!Request.Purpose.IsPublishable())
+        {
+            return MediaResult<MediaJob>.Fail(
+                MediaErrorCode.InvalidTransition,
+                $"job {Id}: finalidade '{Request.Purpose}' nao publica. Rascunho e material interno; " +
+                "promove-lo a publicado apaga a distincao que a finalidade existe para carregar.");
+        }
+
+        if (Request.Purpose.RequiresDisclosure() && disclosure is null)
+        {
+            return MediaResult<MediaJob>.Fail(
+                MediaErrorCode.InvalidTransition,
+                $"job {Id}: finalidade '{Request.Purpose}' exige marcacao visivel e nenhuma foi " +
+                "registrada. C2PA e SynthID vem embutidos e CAEM com screenshot ou re-encode; a " +
+                "marcacao visivel e obrigacao separada, e ela e cobrada AQUI, no ponto de publicacao. " +
+                "Ver ai-agents/media-pipeline.md, secao Marcacao.");
+        }
+
+        return MediaResult<MediaJob>.Ok(this with
+        {
+            State = MediaJobState.Published,
+            PublishedAt = publishedAt,
+            Disclosure = disclosure,
+        });
+    }
+
+    private MediaResult<MediaJob> Invalid(string transition, MediaJobState target)
+        => MediaResult<MediaJob>.Fail(
+            MediaErrorCode.InvalidTransition,
+            $"job {Id}: {transition} pediu '{target}' a partir de '{State}' — essa transicao nao existe.");
+}

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

@@ -0,0 +1,21 @@
+namespace Morph.AiKit.Media;
+
+/// <summary>
+/// A identidade de um job de midia. <b>O unico valor que a superficie publica devolve</b> —
+/// nunca bytes.
+/// </summary>
+/// <remarks>
+/// <c>Guid.CreateVersion7()</c> e nao <c>Guid.NewGuid()</c>: v7 e ordenavel por tempo, o
+/// que mantem o indice do banco do projeto sequencial em vez de espalhar escrita por toda
+/// a arvore. E a regra da casa, escrita aqui porque este e o unico lugar do subsistema que
+/// gera identidade.
+/// </remarks>
+/// <param name="Value">O GUID v7.</param>
+public readonly record struct MediaJobId(Guid Value)
+{
+    /// <summary>Uma identidade nova, ordenavel por tempo.</summary>
+    public static MediaJobId New() => new(Guid.CreateVersion7());
+
+    /// <summary>Forma compacta, para log e URL.</summary>
+    public override string ToString() => Value.ToString("N");
+}