@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

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

@@ -0,0 +1,225 @@
+using System.Runtime.CompilerServices;
+using Microsoft.Extensions.AI;
+
+namespace Morph.AiKit.Tests.Fakes;
+
+/// <summary>
+/// <see cref="IChatClient"/> roteirizado: a costura que dispensa rede e chave de API na
+/// suite inteira do kit.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que ele e o coracao da historia de teste:</b> o unico ponto em que o kit toca um
+/// provider e um <see cref="IChatClient"/>. Trocando esse ponto por uma fila de respostas
+/// escritas a mao, TODO o resto — <c>ModelRegistry</c>, <c>AgentFactory</c>,
+/// <c>UsageCostMiddleware</c>, <c>ConversationStore</c> — passa a ser testavel sem socket,
+/// sem segredo e sem flake. Nenhum tipo desta pasta abre cliente HTTP nem le variavel de
+/// ambiente — o canario estrutural disso e um grep sobre <c>tests/</c> (chave de provider,
+/// leitura de ambiente, cliente HTTP) que precisa voltar VAZIO, e o canario de
+/// comportamento e
+/// <c>FakeChatClientTests.TheWholeSeamAnswersFromMemoryAloneWithNoConfigurationAndNoConnection</c>.
+/// </para>
+/// <para>
+/// <b>Chamada nao roteirizada e defeito de teste, nao "comportamento padrao".</b> Esgotada
+/// a fila, o fake lanca com a contagem exata de chamadas. Devolver uma resposta vazia
+/// silenciosamente faria um teste passar por engano — que e a unica coisa pior do que um
+/// teste falhando.
+/// </para>
+/// <para>Seguro para uso concorrente: fila, contadores e capturas vivem sob um lock unico.</para>
+/// </remarks>
+public sealed class FakeChatClient : IChatClient
+{
+    private readonly Lock _gate = new();
+    private readonly Queue<ChatResponse> _scripted = new();
+    private readonly List<ChatOptions?> _receivedOptions = [];
+    private readonly List<IReadOnlyList<ChatMessage>> _receivedMessages = [];
+
+    /// <summary>Cria um fake com a fila vazia. Enfileire antes de usar.</summary>
+    public FakeChatClient()
+    {
+    }
+
+    /// <summary>Cria um fake ja roteirizado com as respostas dadas, na ordem.</summary>
+    public FakeChatClient(params ChatResponse[] scripted)
+    {
+        ArgumentNullException.ThrowIfNull(scripted);
+
+        foreach (var response in scripted)
+        {
+            _scripted.Enqueue(response);
+        }
+    }
+
+    /// <summary>Atalho: uma resposta de assistente por texto, na ordem dada.</summary>
+    public static FakeChatClient Scripted(params string[] texts)
+    {
+        ArgumentNullException.ThrowIfNull(texts);
+
+        var client = new FakeChatClient();
+        foreach (var text in texts)
+        {
+            client.EnqueueText(text);
+        }
+
+        return client;
+    }
+
+    /// <summary>Quantas vezes o cliente foi invocado (streaming incluso).</summary>
+    public int CallCount { get; private set; }
+
+    /// <summary>
+    /// O <c>ProviderName</c> anunciado no <see cref="ChatClientMetadata"/>. Configuravel
+    /// porque ele ENTRA NA CHAVE da cache de eval: a arvore que este fake grava so e legivel
+    /// depois pelo <c>OfflineChatClient</c> se os dois se apresentarem com a mesma
+    /// identidade. Default preservado ("fake"): quem nao usa eval nao muda de comportamento.
+    /// </summary>
+    public string MetadataProviderName { get; init; } = "fake";
+
+    /// <summary>
+    /// O <c>DefaultModelId</c> anunciado no <see cref="ChatClientMetadata"/>. Tambem entra na
+    /// chave de cache. Nulo por default, como antes.
+    /// </summary>
+    public string? MetadataDefaultModelId { get; init; }
+
+    /// <summary>Se <see cref="Dispose"/> ja foi chamado — usado para provar ownership de cache.</summary>
+    public bool IsDisposed { get; private set; }
+
+    /// <summary>As <see cref="ChatOptions"/> recebidas, uma entrada por chamada, na ordem.</summary>
+    public IReadOnlyList<ChatOptions?> ReceivedOptions
+    {
+        get { lock (_gate) { return [.. _receivedOptions]; } }
+    }
+
+    /// <summary>As mensagens recebidas, uma entrada por chamada, na ordem.</summary>
+    public IReadOnlyList<IReadOnlyList<ChatMessage>> ReceivedMessages
+    {
+        get { lock (_gate) { return [.. _receivedMessages]; } }
+    }
+
+    /// <summary>As opcoes da ultima chamada, ou nulo se nunca foi chamado.</summary>
+    public ChatOptions? LastOptions
+    {
+        get { lock (_gate) { return _receivedOptions.Count == 0 ? null : _receivedOptions[^1]; } }
+    }
+
+    /// <summary>As mensagens da ultima chamada, ou nulo se nunca foi chamado.</summary>
+    public IReadOnlyList<ChatMessage>? LastMessages
+    {
+        get { lock (_gate) { return _receivedMessages.Count == 0 ? null : _receivedMessages[^1]; } }
+    }
+
+    /// <summary>Enfileira uma resposta ja montada. Devolve o proprio fake, para encadear.</summary>
+    public FakeChatClient Enqueue(ChatResponse response)
+    {
+        ArgumentNullException.ThrowIfNull(response);
+
+        lock (_gate)
+        {
+            _scripted.Enqueue(response);
+        }
+
+        return this;
+    }
+
+    /// <summary>
+    /// Enfileira uma resposta de assistente com o texto dado e, opcionalmente, um
+    /// <see cref="UsageDetails"/> controlado — e assim que o teste do
+    /// <c>UsageCostMiddleware</c> (T11) verifica tarifa sem rede.
+    /// </summary>
+    public FakeChatClient EnqueueText(string text, UsageDetails? usage = null)
+        => Enqueue(new ChatResponse(new ChatMessage(ChatRole.Assistant, text)) { Usage = usage });
+
+    /// <summary>
+    /// Enfileira uma resposta com contagem de tokens conhecida. Atalho para o caso mais
+    /// comum de teste de custo.
+    /// </summary>
+    public FakeChatClient EnqueueTextWithUsage(
+        string text,
+        long inputTokens,
+        long outputTokens,
+        long? cachedInputTokens = null)
+        => EnqueueText(
+            text,
+            new UsageDetails
+            {
+                InputTokenCount = inputTokens,
+                OutputTokenCount = outputTokens,
+                TotalTokenCount = inputTokens + outputTokens,
+                CachedInputTokenCount = cachedInputTokens,
+            });
+
+    /// <inheritdoc />
+    public Task<ChatResponse> GetResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(messages);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        return Task.FromResult(Record(messages, options));
+    }
+
+    /// <inheritdoc />
+    public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(messages);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        var response = Record(messages, options);
+
+        foreach (var update in response.ToChatResponseUpdates())
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            yield return update;
+        }
+
+        await Task.CompletedTask.ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public object? GetService(Type serviceType, object? serviceKey = null)
+    {
+        ArgumentNullException.ThrowIfNull(serviceType);
+
+        if (serviceKey is not null)
+        {
+            return null;
+        }
+
+        if (serviceType == typeof(ChatClientMetadata))
+        {
+            return new ChatClientMetadata(MetadataProviderName, providerUri: null, MetadataDefaultModelId);
+        }
+
+        return serviceType.IsInstanceOfType(this) ? this : null;
+    }
+
+    /// <inheritdoc />
+    public void Dispose() => IsDisposed = true;
+
+    private ChatResponse Record(IEnumerable<ChatMessage> messages, ChatOptions? options)
+    {
+        var snapshot = messages as IReadOnlyList<ChatMessage> ?? [.. messages];
+
+        lock (_gate)
+        {
+            CallCount++;
+            _receivedMessages.Add(snapshot);
+            _receivedOptions.Add(options);
+
+            if (_scripted.Count == 0)
+            {
+                throw new InvalidOperationException(
+                    $"FakeChatClient: fila de respostas esgotada na chamada #{CallCount}. " +
+                    "Enfileire com Enqueue/EnqueueText antes de exercitar o caminho — uma " +
+                    "resposta inventada aqui faria o teste passar por engano.");
+            }
+
+            return _scripted.Dequeue();
+        }
+    }
+}

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

@@ -0,0 +1,215 @@
+using Microsoft.Extensions.AI;
+using Morph.AiKit.Providers;
+using Xunit;
+
+namespace Morph.AiKit.Tests.Fakes;
+
+/// <summary>
+/// Canarios da costura de teste (T9). Um fake so vale se ele proprio for testado: um fake
+/// que devolve na ordem errada, ou que engole as <see cref="ChatOptions"/> recebidas,
+/// transforma todo teste que depende dele num teste que nao mede nada.
+/// </summary>
+/// <remarks>
+/// Todo <c>await</c> passa <c>TestContext.Current.CancellationToken</c> porque o analisador
+/// xUnit1051 cobra isso e <c>TreatWarningsAsErrors</c> transforma a cobranca em build
+/// vermelho. Nao ha <c>#pragma</c> aqui: a regra e boa (teste cancelavel) e o custo e um
+/// argumento.
+/// </remarks>
+public sealed class FakeChatClientTests
+{
+    [Fact]
+    public async Task ResponsesComeBackInTheOrderTheyWereEnqueued()
+    {
+        using var client = FakeChatClient.Scripted("primeira", "segunda", "terceira");
+
+        var first = await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "1")],
+            cancellationToken: TestContext.Current.CancellationToken);
+        var second = await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "2")],
+            cancellationToken: TestContext.Current.CancellationToken);
+        var third = await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "3")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(["primeira", "segunda", "terceira"], new[] { first.Text, second.Text, third.Text });
+        Assert.Equal(3, client.CallCount);
+    }
+
+    [Fact]
+    public async Task TheOptionsAndMessagesOfEveryCallAreExposedForInspection()
+    {
+        using var client = FakeChatClient.Scripted("ok", "ok");
+
+        var quente = new ChatOptions { Temperature = 0.9f };
+        var frio = new ChatOptions { Temperature = 0.1f, MaxOutputTokens = 64 };
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "quente")],
+            quente,
+            TestContext.Current.CancellationToken);
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "frio")],
+            frio,
+            TestContext.Current.CancellationToken);
+
+        Assert.Equal([quente, frio], client.ReceivedOptions);
+        Assert.Same(frio, client.LastOptions);
+
+        Assert.Equal(
+            ["quente", "frio"],
+            client.ReceivedMessages.Select(turn => turn[0].Text));
+        Assert.Equal("frio", client.LastMessages![0].Text);
+    }
+
+    [Fact]
+    public async Task OptionsAreCapturedAsNullWhenTheCallerSendsNone()
+    {
+        using var client = FakeChatClient.Scripted("ok");
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Null(Assert.Single(client.ReceivedOptions));
+    }
+
+    [Fact]
+    public async Task AnUnscriptedCallFailsLoudlyInsteadOfInventingAnAnswer()
+    {
+        using var client = FakeChatClient.Scripted("unica");
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "1")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        var error = await Assert.ThrowsAsync<InvalidOperationException>(
+            () => client.GetResponseAsync(
+                [new ChatMessage(ChatRole.User, "2")],
+                cancellationToken: TestContext.Current.CancellationToken));
+
+        Assert.Contains("esgotada na chamada #2", error.Message, StringComparison.Ordinal);
+        Assert.Equal(2, client.CallCount);
+    }
+
+    [Fact]
+    public async Task StreamingReplaysTheSameScriptedResponseAsUpdates()
+    {
+        using var client = FakeChatClient.Scripted("resposta em pedacos");
+
+        var text = string.Empty;
+        var stream = client.GetStreamingResponseAsync(
+            [new ChatMessage(ChatRole.User, "vai")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        await foreach (var update in stream)
+        {
+            text += update.Text;
+        }
+
+        Assert.Equal("resposta em pedacos", text);
+        Assert.Equal(1, client.CallCount);
+    }
+
+    [Fact]
+    public async Task UsageIsControlledByTheTestAndSurvivesTheRoundTrip()
+    {
+        // E assim que a T11 vai verificar tarifa sem rede: Usage conhecido entra,
+        // Usage conhecido sai.
+        using var client = new FakeChatClient();
+        client.EnqueueTextWithUsage("ok", inputTokens: 1_000, outputTokens: 250, cachedInputTokens: 400);
+
+        var response = await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.NotNull(response.Usage);
+        Assert.Equal(1_000, response.Usage.InputTokenCount);
+        Assert.Equal(250, response.Usage.OutputTokenCount);
+        Assert.Equal(1_250, response.Usage.TotalTokenCount);
+        Assert.Equal(400, response.Usage.CachedInputTokenCount);
+    }
+
+    [Fact]
+    public void MetadataIsAnsweredThroughGetServiceLikeARealClient()
+    {
+        using var client = new FakeChatClient();
+
+        var metadata = Assert.IsType<ChatClientMetadata>(client.GetService(typeof(ChatClientMetadata)));
+        Assert.Equal("fake", metadata.ProviderName);
+
+        Assert.Same(client, client.GetService(typeof(IChatClient)));
+        Assert.Null(client.GetService(typeof(IChatClient), serviceKey: "qualquer"));
+    }
+
+    [Fact]
+    public void DisposeIsObservable()
+    {
+        var client = new FakeChatClient();
+
+        Assert.False(client.IsDisposed);
+        client.Dispose();
+        Assert.True(client.IsDisposed);
+    }
+
+    [Fact]
+    public async Task TheWholeSeamAnswersFromMemoryAloneWithNoConfigurationAndNoConnection()
+    {
+        // O caminho inteiro que os consumidores usam — documento JSON, registry, fabrica,
+        // cliente — exercitado com nada alem de objetos em memoria: nenhuma chave, nenhum
+        // arquivo, nenhum socket. E este o teste a apontar quando alguem perguntar "como o
+        // kit testa IA sem provider".
+        //
+        // A propriedade "passa sem chave de provider no ambiente" NAO e afirmada aqui por
+        // codigo: afirma-la exigiria ler variavel de ambiente, e um teste que faz isso
+        // derruba o canario estrutural da T9 — o grep sobre tests/ (chave de provider,
+        // leitura de ambiente, cliente HTTP) tem de voltar VAZIO. A propriedade e
+        // DEMONSTRADA rodando a suite com o ambiente esvaziado, o que cobre os 50 testes
+        // em vez de um.
+        var document = """
+            {
+              "version": "2.0",
+              "defaultAlias": "so-memoria",
+              "aliases": {
+                "so-memoria": {
+                  "provider": "fake",
+                  "model": "modelo-de-teste",
+                  "pricingWaiver": "fake de teste: nao ha tarifa porque nao ha provider."
+                }
+              }
+            }
+            """;
+
+        var scripted = FakeChatClient.Scripted("resposta sem rede");
+        using var registry = ModelRegistry.FromJson(document, new FakeProviderClientFactory(_ => scripted));
+
+        var client = registry.GetChatClient("so-memoria");
+        var response = await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("resposta sem rede", response.Text);
+        Assert.Equal(1, scripted.CallCount);
+    }
+
+    [Fact]
+    public async Task ConcurrentCallersNeverLoseACallOrACapture()
+    {
+        // ConversationStore (T13) exercita duas sessoes sobre a MESMA instancia. Se o fake
+        // perdesse chamada sob concorrencia, aquele teste mediria o fake, nao o store.
+        using var client = new FakeChatClient();
+        for (var i = 0; i < 50; i++)
+        {
+            client.EnqueueText($"r{i}");
+        }
+
+        await Task.WhenAll(Enumerable.Range(0, 50).Select(i =>
+            client.GetResponseAsync(
+                [new ChatMessage(ChatRole.User, $"m{i}")],
+                cancellationToken: TestContext.Current.CancellationToken)));
+
+        Assert.Equal(50, client.CallCount);
+        Assert.Equal(50, client.ReceivedMessages.Count);
+        Assert.Equal(50, client.ReceivedOptions.Count);
+    }
+}

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

@@ -0,0 +1,33 @@
+namespace Morph.AiKit.Tests.Fakes;
+
+/// <summary>
+/// <see cref="TimeProvider"/> controlado pelo teste: o relogio so anda quando o teste manda.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Existe <b>escrito a mao, em 20 linhas</b>, e nao via
+/// <c>Microsoft.Extensions.TimeProvider.Testing</c>, por uma razao de contrato desta
+/// feature: toda versao de pacote vem de <c>framework/ai-pin.json</c>, e aquele pacote nao
+/// esta no pin. Acrescenta-lo seria uma versao decidida fora do pin — exatamente a segunda
+/// verdade que o kit existe para impedir. O achado esta registrado no relatorio da T11.
+/// </para>
+/// <para>
+/// So o necessario esta implementado: <see cref="GetUtcNow"/> e o avanco manual. Timers nao
+/// sao usados por nenhum tipo do kit; herdar o comportamento base e mais honesto que
+/// simular um agendador que ninguem exercita.
+/// </para>
+/// </remarks>
+public sealed class FakeClock(DateTimeOffset start) : TimeProvider
+{
+    private DateTimeOffset _now = start;
+
+    /// <inheritdoc />
+    public override DateTimeOffset GetUtcNow() => _now;
+
+    /// <summary>Avanca o relogio. Rejeita andar para tras: o tempo do teste e monotono.</summary>
+    public void Advance(TimeSpan delta)
+    {
+        ArgumentOutOfRangeException.ThrowIfLessThan(delta, TimeSpan.Zero);
+        _now += delta;
+    }
+}

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

@@ -0,0 +1,89 @@
+using Morph.AiKit.Media;
+
+namespace Morph.AiKit.Tests.Fakes;
+
+/// <summary>
+/// <see cref="IMediaProvider"/> roteirizado: a costura que dispensa rede, chave de API e
+/// <b>fatura</b> na suite inteira de midia.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que ele existe:</b> o unico ponto do subsistema que gasta dinheiro e um
+/// <c>IMediaProvider</c>. Trocando-o por uma fila de respostas escritas a mao, todo o resto
+/// — <c>MediaGenerator</c>, <c>MediaWorker</c>, <c>MediaJob</c>, <c>MediaStore</c> — passa a
+/// ser testavel sem socket, sem segredo e sem cobranca. Mesmo desenho do
+/// <see cref="FakeChatClient"/>, pela mesma razao.
+/// </para>
+/// <para>
+/// Ele so e construivel porque <c>InternalsVisibleTo("Morph.AiKit.Tests")</c> existe no
+/// <c>.csproj</c> da biblioteca. Um projeto consumidor <b>nao</b> consegue escrever esta
+/// classe — e essa impossibilidade e a regra dura de <c>ai-agents/media-pipeline.md</c>,
+/// asserida em <c>MediaAccessibilityTests</c>.
+/// </para>
+/// <para>
+/// <b>Chamada nao roteirizada e defeito de teste.</b> Esgotada a fila, o fake devolve uma
+/// falha nomeada com a contagem de chamadas, em vez de inventar bytes — um artefato
+/// fabricado pelo proprio fake faria um teste passar por engano.
+/// </para>
+/// </remarks>
+internal sealed class FakeMediaProvider : IMediaProvider
+{
+    private readonly Queue<MediaResult<MediaArtifact>> _scripted = new();
+    private readonly Lock _gate = new();
+
+    public FakeMediaProvider(string provider = "fake", MediaKind supports = MediaKind.Image)
+    {
+        Provider = provider;
+        Supported = supports;
+    }
+
+    /// <inheritdoc />
+    public string Provider { get; }
+
+    /// <summary>Que tipo de midia este fake diz atender.</summary>
+    public MediaKind Supported { get; }
+
+    /// <summary>Quantas vezes foi chamado. E como um teste prova que NAO houve segunda chamada paga.</summary>
+    public int Calls { get; private set; }
+
+    /// <summary>Os pedidos vistos, na ordem.</summary>
+    public List<MediaRequest> Seen { get; } = [];
+
+    /// <summary>Enfileira bytes de sucesso.</summary>
+    public FakeMediaProvider Returns(byte[] bytes, string mediaType = "image/png", string? revisedPrompt = null)
+    {
+        _scripted.Enqueue(MediaResult<MediaArtifact>.Ok(new MediaArtifact(
+            Supported, mediaType, bytes, revisedPrompt, ResponseId: "resp-fake", C2paPreserved: true)));
+        return this;
+    }
+
+    /// <summary>Enfileira uma recusa com o codigo dado — inclusive <c>PolicyBlocked</c>.</summary>
+    public FakeMediaProvider Fails(MediaErrorCode code, string message = "roteirizado")
+    {
+        _scripted.Enqueue(MediaResult<MediaArtifact>.Fail(code, message));
+        return this;
+    }
+
+    /// <inheritdoc />
+    public bool Supports(MediaKind kind) => kind == Supported;
+
+    /// <inheritdoc />
+    public Task<MediaResult<MediaArtifact>> ProduceAsync(
+        MediaRequest request,
+        MediaAliasBinding binding,
+        CancellationToken cancellationToken)
+    {
+        lock (_gate)
+        {
+            Calls++;
+            Seen.Add(request);
+
+            return Task.FromResult(_scripted.Count > 0
+                ? _scripted.Dequeue()
+                : MediaResult<MediaArtifact>.Fail(
+                    MediaErrorCode.ProviderFailure,
+                    $"FakeMediaProvider: chamada {Calls} nao roteirizada. Um fake que inventa bytes faz " +
+                    "um teste passar por engano."));
+        }
+    }
+}

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

@@ -0,0 +1,55 @@
+using Microsoft.Extensions.AI;
+using Morph.AiKit.Providers;
+
+namespace Morph.AiKit.Tests.Fakes;
+
+/// <summary>
+/// <see cref="IProviderClientFactory"/> de teste: devolve <see cref="FakeChatClient"/> e
+/// <b>conta quantas vezes foi chamada</b>. E o contador que torna a memoizacao do
+/// <c>ModelRegistry</c> uma afirmacao verificavel em vez de uma promessa.
+/// </summary>
+public sealed class FakeProviderClientFactory : IProviderClientFactory
+{
+    private readonly Func<ModelAlias, IChatClient?> _create;
+    private readonly Dictionary<string, IChatClient> _created = new(StringComparer.Ordinal);
+    private readonly List<ModelAlias> _requested = [];
+
+    /// <summary>Fabrica que devolve um <see cref="FakeChatClient"/> novo por alias.</summary>
+    public FakeProviderClientFactory()
+        : this(_ => new FakeChatClient())
+    {
+    }
+
+    /// <summary>
+    /// Fabrica com construcao sob medida — inclusive devolvendo nulo, para exercitar a
+    /// recusa do registry a um cliente inexistente.
+    /// </summary>
+    public FakeProviderClientFactory(Func<ModelAlias, IChatClient?> create)
+        => _create = create;
+
+    /// <summary>Quantas vezes <see cref="CreateChatClient"/> foi realmente executada.</summary>
+    public int CreateCount { get; private set; }
+
+    /// <summary>Os aliases para os quais um cliente foi criado, na ordem.</summary>
+    public IReadOnlyList<ModelAlias> Requested => _requested;
+
+    /// <summary>Os clientes criados, por nome de alias.</summary>
+    public IReadOnlyDictionary<string, IChatClient> Created => _created;
+
+    /// <inheritdoc />
+    public IChatClient CreateChatClient(ModelAlias alias)
+    {
+        ArgumentNullException.ThrowIfNull(alias);
+
+        CreateCount++;
+        _requested.Add(alias);
+
+        var client = _create(alias);
+        if (client is not null)
+        {
+            _created[alias.Name] = client;
+        }
+
+        return client!;
+    }
+}

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

@@ -0,0 +1,60 @@
+using Morph.AiKit.Middleware;
+
+namespace Morph.AiKit.Tests.Fakes;
+
+/// <summary>
+/// Sink de teste: acumula os registros de custo publicados pelo
+/// <see cref="UsageCostMiddleware"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Estava nos <c>outputs</c> da T9, mas depende de <see cref="IUsageCostSink"/> e
+/// <see cref="UsageCostRecord"/>, que sao <c>outputs</c> da T11. A T9 recusou-se a criar os
+/// dois tipos por fora (seriam arquivos de outra task, e duplica-los criaria a segunda
+/// verdade do registro de custo) e deixou este codigo pronto no seu relatorio; a errata E8
+/// do <c>spec.md</c> moveu formalmente o arquivo para ca. Nasce junto dos tipos que
+/// implementa.
+/// </para>
+/// <para>
+/// Seguro sob concorrencia pelo mesmo motivo do <see cref="FakeChatClient"/>: um mesmo
+/// pipeline atende varias conversas, e um sink que perdesse linha sob concorrencia faria o
+/// teste medir o sink em vez do middleware.
+/// </para>
+/// </remarks>
+public sealed class FakeUsageCostSink : IUsageCostSink
+{
+    private readonly Lock _gate = new();
+    private readonly List<UsageCostRecord> _records = [];
+
+    /// <summary>Tudo o que foi publicado, na ordem. Snapshot — iterar e seguro.</summary>
+    public IReadOnlyList<UsageCostRecord> Records
+    {
+        get { lock (_gate) { return [.. _records]; } }
+    }
+
+    /// <summary>O ultimo registro publicado, ou nulo se nenhum foi.</summary>
+    public UsageCostRecord? Last
+    {
+        get { lock (_gate) { return _records.Count == 0 ? null : _records[^1]; } }
+    }
+
+    /// <summary>Quantas linhas de custo foram publicadas.</summary>
+    public int Count
+    {
+        get { lock (_gate) { return _records.Count; } }
+    }
+
+    /// <summary>A soma dos custos <b>medidos</b> — os demais status nao entram na conta.</summary>
+    public decimal MeasuredTotalUsd
+    {
+        get { lock (_gate) { return _records.Where(r => r.IsMeasuredCost).Sum(r => r.CostUsd); } }
+    }
+
+    /// <inheritdoc />
+    public void Record(UsageCostRecord record)
+    {
+        ArgumentNullException.ThrowIfNull(record);
+
+        lock (_gate) { _records.Add(record); }
+    }
+}