@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/standards/ai-agents/sweet-spot.md

@@ -1,109 +1,129 @@
-# Sweet Spot — When to use what in MAF
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 0 (always-load via persona maf-expert)
-> **Keywords:** sweet spot, when to use agent, agent vs workflow, when not to use workflow, MAF decision, simple agent
-> **Read by Claude in:** plan (decide arquitetura da feature antes de quebrar em tasks) + implement (validar que a arquitetura ainda é a mais simples possível)
-
-**Verified against:** MAF Tier List research (2026-05-18) + Microsoft Learn docs. Last-verified: 2026-05-19.
-
----
-
-## The 4-feature rule
-
-```
-95% of production AI agents need ONLY:
-
-  1. Chat (the LLM call)
-  2. Structured Output (typed records, not free text)
-  3. Tools (typed functions the agent can call)
-  4. RAG Custom (pgvector tool, not hosted RAG)
-
-If your feature needs ONLY these 4 → use a single agent. Don't reach for workflows.
-```
-
-Apply this rule before deciding multi-agent or workflow. Most of the time the answer is "single agent".
-
----
-
-## Decision tree (Claude reads this in plan phase)
-
-```
-Step 1 — Does the task even need an LLM?
-├─ "Can a deterministic function solve this?" → YES → write the function, no agent
-└─ NO → continue
-
-Step 2 — Single agent vs multi-agent?
-├─ One topic + one decision → single agent (DEFAULT)
-├─ Multiple specialized topics with clear handoff → multi-agent
-│   └─ Prefer Agent-as-Tool pattern (one agent uses another as a tool)
-│   └─ See ai-agents-multi-agent-patterns
-└─ "I'm not sure" → start with single agent, escalate if needed
-
-Step 3 — Need a Workflow?
-├─ The feature has fan-in/out (many inputs aggregated) → maybe workflow
-│   └─ Confirm: can you write it as a foreach + LINQ aggregate?
-│       └─ YES → write the foreach, NO workflow
-│       └─ NO → workflow may help
-├─ Long-running with human-in-the-loop checkpoints → maybe workflow
-│   └─ See ai-agents-workflows (Onda 2)
-└─ Otherwise → NO workflow
-
-Step 4 — Which provider?
-├─ ALWAYS direct models — never a hosted agent service
-├─ Provider choice (OpenAI / Google / Anthropic / Ollama) lives in the
-│  project's Model Registry, not hardcoded → see ai-agents-providers-model-registry
-└─ Hosted services (Foundry Agent Service, Vertex AI hosted) → NOT used
-
-Step 5 — RAG approach?
-├─ Need control over chunking/embedding/storage? → RAG custom (pgvector)
-│   └─ See ai-agents-rag-custom-pgvector (Onda 2)
-└─ Don't reach for hosted RAG — loses control
-```
-
----
-
-## Anti-patterns (what Claude should NOT do)
-
-| Anti-pattern | Why it's wrong | What to do instead |
-|--------------|----------------|---------------------|
-| Reach for Workflow when a function does the job | "Tudo que Workflows fazem, código C# normal faz com menos complexidade" — pesquisa | Write the function. Wrap in a tool if an agent needs to call it. |
-| Use a hosted agent service | Hosted is "always 6-9 months behind" on models + removes control | Direct models always (OpenAI / Google / Anthropic / Ollama) |
-| Upload PDFs to a hosted RAG | Loses control of chunking + embedding + storage | Custom RAG with pgvector. See ai-agents-rag-custom-pgvector |
-| Add Memory/Session because "agents need state" | If not building a chatbot, don't add chat state | Skip. Add when a real chat UI exists. |
-| Use Semantic Kernel for new features | SK is superseded by MAF | Use Microsoft.Agents.AI. See ai-agents-setup |
-| Return free text and parse it downstream | LLM output is non-deterministic | Structured Output. See ai-agents-structured-output (Onda 2) |
-
----
-
-## When the 4-feature rule does NOT apply
-
-You may need to step outside the sweet spot when:
-- The feature genuinely fans-out (e.g., monthly report aggregating N items) → workflow with fan-in
-- The feature needs vision/audio/image-gen → modality-specific standards (see ai-agents-modalities-* — Onda 3)
-
-**Even in these cases:** the core of the agent still follows the 4-feature rule. Only the orchestration layer changes.
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] Was each agent designed as single-agent BEFORE reaching for multi-agent? (Check `decisions.md`.)
-- [ ] If a Workflow is used, is fan-in/out or HITL checkpointing genuinely present? Or could `foreach + LINQ` replace it?
-- [ ] Are the 4 features (Chat, Structured Output, Tools, RAG Custom) all present where applicable?
-- [ ] Are hosted agent services avoided?
-
----
-
-## References
-
-- `ai-agents-setup` — packages and DI
-- `ai-agents-providers-model-registry` — provider-agnostic config
-- `ai-agents-structured-output` (Onda 2)
-- `ai-agents-multi-agent-patterns` (Onda 2)
-- `ai-agents-workflows` (Onda 2, reframed)
-- `ai-agents-rag-custom-pgvector` (Onda 2)
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/sweet-spot.md v1.0 (2026-05-19)*
+# Sweet Spot — When to use what in MAF
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 0 (always-load via persona maf-expert)
+> **Keywords:** sweet spot, when to use agent, agent vs workflow, when not to use workflow, MAF decision, simple agent, tool budget, quantas tools
+> **Read by Claude in:** plan (decide arquitetura da feature antes de quebrar em tasks) + implement (validar que a arquitetura ainda é a mais simples possível)
+
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Agents.AI.Workflows 1.20.0 (ai-pin 2026-09-08 para o primeiro; o segundo está **fora do pin**, versão apurada no nuget.org em 2026-09-08). **Verificação documental**, sem cláusula `provado por` — este standard é decisão de arquitetura, não API. A escada de complexidade foi reconferida e **continua correta**; o que entrou de novo é o custo de definição de tool por turno e o status do Handoff. Last-verified: 2026-09-08.
+
+---
+
+## The 4-feature rule
+
+```
+95% of production AI agents need ONLY:
+
+  1. Chat (the LLM call)
+  2. Structured Output (typed records, not free text)
+  3. Tools (typed functions the agent can call)
+  4. RAG Custom (pgvector tool, not hosted RAG)
+
+If your feature needs ONLY these 4 → use a single agent. Don't reach for workflows.
+```
+
+Apply this rule before deciding multi-agent or workflow. Most of the time the answer is "single agent".
+
+### O quinto sinal: quantas tools o agente carrega
+
+A regra das 4 features diz **o que** o agente faz. Falta **quanto** ele carrega — e esse é o custo que ninguém vê no código.
+
+**Toda tool registrada entra na definição enviada ao modelo em CADA turno**: nome, descrição e o JSON Schema completo dos parâmetros. Um agente com 40 tools paga esses 40 schemas de entrada em todo turno, inclusive nos turnos em que nenhuma tool é chamada — e paga de novo em cada volta do laço de tool calling.
+
+**Referência prática: ≤ 12 tools por agente.** Acima disso, dois efeitos se somam, e o segundo é pior que o primeiro:
+
+1. **Custo por turno cresce** com o tamanho da definição.
+2. **A escolha piora.** Quanto mais tools parecidas, mais o modelo erra qual chamar — e um erro de escolha custa uma volta inteira.
+
+**Quando estourar o teto, na ordem:** (a) **poda** — remova o que não é usado naquele modo; (b) **plano por fase** — uma allow-list por estado do funil, montada em C# (`ai-agents-context-providers` §Ordem de escolha); (c) **só então** agent-as-tool, com o auxiliar carregando o próprio subconjunto (`ai-agents-multi-agent-patterns`). Servidor MCP com dezenas de tools é o caso mais comum de estouro — ver `ai-agents-mcp-tools` §Custo de definição de tool por turno.
+
+### Status do Handoff (2026-09-08)
+
+O Handoff era marcado **experimental** no 1.0 e **graduou**: `Microsoft.Agents.AI.Workflows.HandoffWorkflowBuilder` **não carrega** `[Experimental]` na assembly 1.20.0 (medido). Isso muda o degrau da escada: handoff deixou de ser "experimental, evite" e passou a ser "estável, mas ainda depois de agent-as-tool" — a ordem de preferência **não** mudou, o motivo mudou. O critério continua o mesmo: agent-as-tool primeiro, handoff quando há N especialistas e a decisão de roteamento não cabe numa tool.
+
+---
+
+## Decision tree (Claude reads this in plan phase)
+
+```
+Step 1 — Does the task even need an LLM?
+├─ "Can a deterministic function solve this?" → YES → write the function, no agent
+└─ NO → continue
+
+Step 2 — Single agent vs multi-agent?
+├─ One topic + one decision → single agent (DEFAULT)
+├─ Multiple specialized topics with clear handoff → multi-agent
+│   └─ Prefer Agent-as-Tool pattern (one agent uses another as a tool)
+│   └─ See ai-agents-multi-agent-patterns
+└─ "I'm not sure" → start with single agent, escalate if needed
+
+Step 3 — Need a Workflow?
+├─ The feature has fan-in/out (many inputs aggregated) → maybe workflow
+│   └─ Confirm: can you write it as a foreach + LINQ aggregate?
+│       └─ YES → write the foreach, NO workflow
+│       └─ NO → workflow may help
+├─ Long-running with human-in-the-loop checkpoints → maybe workflow
+│   └─ See ai-agents-workflows (Onda 2)
+└─ Otherwise → NO workflow
+
+Step 4 — Which provider?
+├─ ALWAYS direct models — never a hosted agent service
+├─ Provider choice (OpenAI / Google / Anthropic / Ollama) lives in the
+│  project's Model Registry, not hardcoded → see ai-agents-providers-model-registry
+└─ Hosted services (Foundry Agent Service, Vertex AI hosted) → NOT used
+
+Step 5 — RAG approach?
+├─ Need control over chunking/embedding/storage? → RAG custom (pgvector)
+│   └─ See ai-agents-rag-custom-pgvector (Onda 2)
+└─ Don't reach for hosted RAG — loses control
+```
+
+---
+
+## Anti-patterns (what Claude should NOT do)
+
+| Anti-pattern | Why it's wrong | What to do instead |
+|--------------|----------------|---------------------|
+| Reach for Workflow when a function does the job | "Tudo que Workflows fazem, código C# normal faz com menos complexidade" — pesquisa | Write the function. Wrap in a tool if an agent needs to call it. |
+| Use a hosted agent service | Hosted is "always 6-9 months behind" on models + removes control | Direct models always (OpenAI / Google / Anthropic / Ollama) |
+| Upload PDFs to a hosted RAG | Loses control of chunking + embedding + storage | Custom RAG with pgvector. See ai-agents-rag-custom-pgvector |
+| Add Memory/Session because "agents need state" | If not building a chatbot, don't add chat state | Skip. Add when a real chat UI exists. |
+| Use Semantic Kernel for new features | SK is superseded by MAF | Use Microsoft.Agents.AI. See ai-agents-setup |
+| Return free text and parse it downstream | LLM output is non-deterministic | Structured Output. See ai-agents-structured-output (Onda 2) |
+
+---
+
+## When the 4-feature rule does NOT apply
+
+You may need to step outside the sweet spot when:
+- The feature genuinely fans-out (e.g., monthly report aggregating N items) → workflow with fan-in
+- The feature needs vision/audio/image-gen → modality-specific standards (see ai-agents-modalities-* — Onda 3)
+
+**Even in these cases:** the core of the agent still follows the 4-feature rule. Only the orchestration layer changes.
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Was each agent designed as single-agent BEFORE reaching for multi-agent? (Check `decisions.md`.)
+- [ ] If a Workflow is used, is fan-in/out or HITL checkpointing genuinely present? Or could `foreach + LINQ` replace it?
+- [ ] Are the 4 features (Chat, Structured Output, Tools, RAG Custom) all present where applicable?
+- [ ] Are hosted agent services avoided?
+- [ ] Nenhum agente carrega mais de ~12 tools sem uma decisão escrita em `decisions.md` sobre a poda
+
+---
+
+## References
+
+- `ai-agents-setup` — packages and DI
+- `ai-agents-providers-model-registry` — provider-agnostic config
+- `ai-agents-structured-output` (Onda 2)
+- `ai-agents-multi-agent-patterns` (Onda 2)
+- `ai-agents-workflows` (Onda 2, reframed)
+- `ai-agents-rag-custom-pgvector` (Onda 2)
+- `ai-agents-mcp-tools` — o caso mais comum de estouro do teto de tools
+- `ai-agents-context-providers` — plano por fase com allow-list de tools
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/sweet-spot.md v1.1 (2026-09-08)*

package/framework/standards/ai-agents/testing-ai.md

@@ -0,0 +1,236 @@
+# Testing AI — como se testa um agente sem rede, sem chave e sem variância
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** testar agente, fake IChatClient, ScriptedChatClient, harness de turno, eval de agente, teste sem rede, golden de prompt, compatibilidade binaria
+> **Read by Claude in:** implement (ao escrever o teste de qualquer código que fala com um modelo)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/Fakes/FakeChatClient.cs` e `.../src/Morph.AiKit/Providers/IProviderClientFactory.cs` — o fake roteirizado e a costura que dispensa rede são o que o kit compila e exercita. Harness de turno completo e evals com cache de resposta são **verificação documental** — o ai-kit não os traz. Last-verified: 2026-09-08.
+
+---
+
+## Fronteira com o testing genérico
+
+`backend-dotnet-testing` continua dono do que é de teste em .NET: xUnit, `FakeTimeProvider`,
+isolamento entre casos, nomes de teste, organização de fixtures. **Nada disso se repete aqui.**
+
+Este standard cobre **só o que é de agente** — e o que é de agente cabe em uma frase: o único ponto
+em que o seu código toca um provider é um `IChatClient`. Todo o resto deste arquivo é consequência
+disso.
+
+---
+
+## Fake de IChatClient
+
+**Roteirizado e burro.** Uma fila de respostas escritas à mão, servidas na ordem:
+
+- resposta de texto;
+- resposta com chamada de função (`FunctionCallContent`);
+- resposta de texto com uso preenchido (para exercitar a conta de custo).
+
+A fila guarda **respostas**, não exceções: no exemplar do kit, os três métodos de enfileiramento
+recebem `ChatResponse` (direto, por texto, ou por texto + uso), e o único `throw` do fake é o de
+**fila esgotada**. Para exercitar o caminho de falha do provider, injete um cliente que lança em vez
+de enfileirar uma exceção — são costuras diferentes, e confundi-las faz o teste de falha passar pelo
+motivo errado.
+
+E do outro lado, **captura**: as mensagens recebidas, as opções recebidas e a contagem de chamadas —
+uma entrada por chamada, na ordem. É o que permite assertar *o que foi ao provedor*, e não apenas
+*o que voltou*.
+
+**A regra que define o padrão: o fake não pode ser inteligente.** Ele não escolhe resposta por
+conteúdo, não simula um modelo, não "responde razoavelmente". E, esgotada a fila, **ele lança**, com
+a contagem exata de chamadas. Devolver uma resposta vazia em silêncio faria um teste passar por
+engano — que é a única coisa pior do que um teste falhando.
+
+O argumento mais forte a favor desta forma não é teórico: **duas implementações independentes, em
+dois produtos que não se conhecem, chegaram à mesma coisa** (um `FakeChatClient` e um
+`ScriptedChatClient`, com a mesma fila e a mesma captura). O ai-kit compila a terceira.
+
+### A costura, e por que `sealed` não é desculpa para abri-la
+
+O fake só serve se houver **um** ponto de injeção. No kit, esse ponto é uma interface de uma
+operação — dado um alias resolvido, devolva o `IChatClient`. O registry permanece `sealed` e continua
+sem saber construir cliente de provider nenhum.
+
+> **O que o kit traz, e o que ele não traz.** A única implementação dessa interface no kit é a de
+> **teste** (`FakeProviderClientFactory`) — medido. O adaptador de produção, aquele que faz o
+> `switch` por provider e constrói o cliente de verdade, é **seu**: o kit prova que a costura
+> funciona, não que o outro lado dela existe. É a mesma distinção de níveis do resto deste standard.
+
+Precedente de campo com a **variante**: quando o registry é `sealed` e não se quer uma interface
+pública, a costura foi um **construtor `internal`** recebendo uma função `alias -> IChatClient`,
+exposta ao projeto de teste. As duas formas resolvem o mesmo problema; ambas preservam `sealed`, que
+é a política da casa. **Costura de teste não é justificativa para tornar uma classe herdável.**
+
+---
+
+## Harness de turno
+
+**Rode o loop real por cima do fake.** O valor não está em testar o fake; está em fazer o cliente de
+invocação de funções **real** chamar as tools **reais**, com os clientes externos mockados.
+
+É assim que se prova, sem rede e sem chave de API:
+
+- que a tool escolhida foi a certa para aquele estado;
+- que os argumentos montados batem;
+- que o guard barrou o que devia barrar;
+- que o teto de tool calls encerrou o turno onde devia;
+- que o custo somou o que devia somar.
+
+Nenhuma dessas cinco coisas é observável testando o compositor isolado — todas dependem do loop.
+
+**Nota de ownership de recurso:** quem cria o cliente e quem o descarta precisa ser decidido uma vez.
+Se a fábrica guardasse e reaproveitasse clientes por fora, existiriam duas caches da mesma coisa — e
+duas caches da mesma coisa é como um cliente vazado sobrevive a um teste e polui o seguinte.
+
+---
+
+## Eval e unit
+
+**"Eval" aqui não significa "modelo real".**
+
+O padrão medido, e é o que dá mais retorno por hora escrita, é o **eval determinístico**: exercitar o
+caminho **completo e real** — processador de turno, compositor, runner com middleware, tools,
+persistência — com o comportamento do modelo **roteirizado**. Ganha-se cobertura de decisão sem
+variância, e o teste falha por um motivo legível em vez de "o modelo respondeu diferente hoje".
+
+Para o que **precisa** do modelo de verdade, o passo seguinte é uma biblioteca de avaliação com
+**cache de resposta**, em **categoria própria** de teste — nunca misturada à suíte determinística. E
+a regra que fecha: **gate duro só vale sobre propriedade determinística.** Reprovar um build porque
+uma nota subjetiva caiu de 8,1 para 7,9 é transformar ruído em bloqueio.
+
+**Zero chamada real ao provider dentro do `dotnet test`.** É uma propriedade **verificável
+mecanicamente**, e o jeito de verificá-la é uma varredura sobre `tests/` procurando chave de
+provider, leitura de variável de ambiente e cliente HTTP: ela precisa voltar **vazia**.
+
+> **Quem faz essa varredura hoje: ninguém, automaticamente.** Medido em 2026-09-08 sobre o ai-kit
+> (`grep -rniE "OPENAI_API_KEY|GetEnvironmentVariable|HttpClient|EnumerateFiles|Directory.Get"` em
+> `templates/dotnet/ai-kit/**`): **zero ocorrências** — o que prova que o kit **não chama** o
+> provider, e simultaneamente que **não existe teste que cobre essa ausência**. O kit descreve a
+> propriedade em prosa (`FakeChatClient.cs`), não a guarda. Adotar esta regra significa **escrever a
+> varredura no seu projeto**; herdá-la do kit é herdar uma intenção.
+
+A medição de campo que sustenta a regra é do **acervo**, não do kit: `grep -c OPENAI_API_KEY` em
+`tests/` = 0, sem nenhum teste marcado como pulado nem categoria de exclusão — ou seja, não há
+"teste real desligado", há ausência de teste real.
+
+**E o standard registra o preço disso**, porque ele é real: o harness com modelo de verdade daquele
+projeto (onze cenários) **nunca foi rodado por completo ao vivo**. O que fica fora do `dotnet test`
+tende a não rodar. Se um caminho precisa do modelo real, ele precisa de um dono e de um gatilho — ou
+vai apodrecer.
+
+---
+
+## Captura do que foi ao provedor
+
+O que se quer saber depois de um bug é: **o que exatamente foi enviado?**
+
+Os dois artefatos que existem no campo, e nenhum deles se chama "captura da chamada crua":
+
+1. **As opções recebidas pelo fake** — em teste, é a prova direta de que a lista de tools ofertadas
+   saiu da lista real, de que o modo de tool era o esperado, e de que o esforço de raciocínio foi o
+   do alias.
+2. **O hash do texto que foi ao provedor** — em produção.
+
+**A regra: prompt cru só em desenvolvimento e no harness, com opt-in explícito e sem dado pessoal;
+em produção, hash.** Um prompt cru persistido em produção é um vazamento esperando indexação.
+
+Duas asserções que o campo escreveu e que valem copiar: que a lista de tools ofertadas **saiu da
+lista real** (e não de uma constante paralela), e que **turno cancelado não grava** — porque um
+registro de algo que não aconteceu é pior que ausência de registro.
+
+A metade de produção deste assunto — como o hash vira span, e a invariante que o torna confiável —
+é de `ai-agents-observability-patterns`.
+
+---
+
+## Golden com parcimônia
+
+Golden test congela uma saída em arquivo e compara. É excelente onde o **contrato é a forma**, e é
+peso morto onde o conteúdo muda por motivo legítimo.
+
+**Onde compensa:** o render de uma persona a partir de blocos, o contrato de saída estruturada, o
+formato de um artefato publicado.
+
+**Onde não compensa, com contra-exemplo real:** goldens de dois blobs de prompt foram **removidos de
+propósito** de um projeto, com a justificativa medida — *"13,6 KB congelados para provar duas linhas
+de concatenação"*. Cada edição de prompt exigia regravar 13,6 KB, o diff era ilegível, e a revisão
+virava um "aceitar tudo". Um golden que ninguém lê no diff não é teste: é atrito.
+
+O critério: **golden prova forma, não conteúdo.** Se a asserção real é "estas duas linhas
+concatenam", escreva as duas linhas.
+
+### Teste de compatibilidade binária
+
+Técnica, não filosofia: comparar em runtime a versão do assembly do SDK carregado com a que a ponte
+referencia, e conferir a **assinatura** do membro que já quebrou uma vez. É barato, roda sem rede, e
+pega a classe de defeito que custou uma chamada paga sem resposta. Ponte com
+`ai-agents-llm-runtime-defaults`, seção de pin de SDK.
+
+### Prompt versionado é texto testável
+
+Quando o prompt vive fora do código, ele continua sendo texto — e texto se testa. Ler a fonte
+versionada e assertar:
+
+- **presença** de uma regra que precisa estar lá;
+- **vocabulário** das chaves que o consumidor espera;
+- **ausência** de uma instrução revogada — que é a asserção que ninguém escreve e a que mais pega
+  regressão.
+
+Precedente de campo: treze arquivos e cerca de 2.500 linhas fazendo exatamente isso. Ponte com
+`ai-agents-prompt-sources`, seção de reconciliação.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Fake "inteligente" que escolhe resposta por conteúdo | Você passa a testar o fake | Fila roteirizada, servida na ordem |
+| Fake que devolve vazio quando a fila acaba | O teste passa por engano | Lance, com a contagem de chamadas |
+| Testar só o compositor, sem o loop real | Tool escolhida, guard e teto ficam sem cobertura | Harness com o cliente de invocação real |
+| Chamada real ao provider dentro do `dotnet test` | Custo, flake e dependência de rede na suíte | Zero; e verifique com varredura |
+| Harness com modelo real sem dono nem gatilho | Onze cenários que nunca rodaram por completo | Dono, gatilho e categoria própria |
+| Gate duro sobre nota subjetiva de eval | Ruído virando bloqueio de build | Gate só sobre propriedade determinística |
+| Prompt cru persistido em produção | Vazamento esperando indexação | Hash em produção; cru só em dev/harness com opt-in |
+| Gravar telemetria de turno cancelado | Registro de algo que não aconteceu | Não grave |
+| Golden de blob de prompt | 13,6 KB congelados para provar duas linhas | Asserte as duas linhas |
+| Abrir a classe (`sealed` removido) para poder testar | Costura de teste virando decisão de arquitetura | Interface de uma operação, ou construtor `internal` |
+| Fábrica que guarda e reaproveita clientes por fora | Duas caches da mesma coisa; cliente vazado entre testes | Ownership decidido num lugar |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Existe um fake de `IChatClient` roteirizado, com captura de mensagens, opções e contagem
+- [ ] O fake **lança** quando a fila acaba
+- [ ] Há ao menos um teste que roda o loop **real** de invocação de funções por cima do fake
+- [ ] Existe **no seu projeto** um teste que varre `tests/` por chave de provider, leitura de ambiente
+      e cliente HTTP, e ele volta vazio (o ai-kit **não** traz essa varredura — medido; herdá-la do
+      kit é herdar uma intenção)
+- [ ] Nenhum teste real de modelo está apenas "pulado" — ou tem dono e gatilho, ou não existe
+- [ ] Nenhum gate duro sobre nota subjetiva de eval
+- [ ] Existe asserção de que a lista de tools ofertadas saiu da lista real
+- [ ] Turno cancelado não grava telemetria
+- [ ] Nenhum golden de blob de prompt; goldens existentes provam **forma**
+- [ ] Existe teste de compatibilidade binária do par SDK × ponte
+- [ ] O prompt versionado tem teste de texto, incluindo **ausência** de instrução revogada
+- [ ] Nenhuma classe deixou de ser `sealed` por causa de teste
+
+---
+
+## References
+
+- `backend-dotnet-testing` — dono do testing .NET genérico (xUnit, `FakeTimeProvider`, isolamento).
+  Nada dele se repete aqui
+- `ai-agents-llm-runtime-defaults` — o pin de SDK que o teste de compatibilidade binária protege
+- `ai-agents-prompt-sources` — a fonte versionada que o teste de prompt como texto lê
+- `ai-agents-observability-patterns` — a metade de produção da captura (hash, span, invariante)
+- `ai-agents-conversational-agent-with-phases` — compositor, allow-list e teto: o que o harness exercita
+- `ai-agents-cost-and-budget` — a conta que o harness confere com uso roteirizado
+- `ai-agents-guardrails` — os guards que só o loop real prova
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/testing-ai.md v1.0 (2026-09-08)*

package/framework/standards/ai-agents/vector-data-extensions.md

@@ -5,7 +5,7 @@
 > **Keywords:** microsoft extensions vectordata, vectorstorecollection, vector store abstraction, data ingestion, ingestion pipeline, semantic kernel connectors exception, pgvector connector, vectorstorewriter
 > **Read by Claude in:** plan (when choosing a RAG storage backend) + implement (when deciding whether to adopt VectorData over custom pgvector)
 
-**Verified against:** Microsoft.Extensions.VectorData.Abstractions GA (`dotnet/extensions`, transferred from the Semantic Kernel repo) + Microsoft.Extensions.DataIngestion 10.0.1-preview.1.25571.5 + Microsoft.SemanticKernel.Connectors.PgVector 1.74.0-preview. Last-verified: 2026-07-06.
+**Verified against:** Microsoft.Extensions.VectorData.Abstractions **10.9.0** + CommunityToolkit.VectorData.PgVector **1.0.1** + Microsoft.Extensions.DataIngestion **10.9.0-preview.1.26411.16** — nenhum deles está no `framework/ai-pin.json` (que cobre os 5 pacotes de agente), portanto **todas as versões acima foram apuradas na API do nuget.org em 2026-09-08** e são citadas com essa data, não como pin. **Verificação documental**, sem cláusula `provado por`: o ai-kit **não referencia nem exercita** VectorData — o pacote não está no `Morph.AiKit.csproj`, cujos cinco `PackageReference` são exatamente os do pin (medido 2026-09-08). Aqui nem a régua fraca do restore existe. Last-verified: 2026-09-08.
 
 ---
 
@@ -33,7 +33,23 @@ A single `VectorStoreCollection<TKey, TRecord>` shape works identically whether
 
 ## A pegadinha de nomenclatura (crítico — leia antes de tudo)
 
-The concrete vector-store **connectors** — the packages that actually implement `VectorStoreCollection` against a real backend — ship under `Microsoft.SemanticKernel.Connectors.*` package names (`Microsoft.SemanticKernel.Connectors.PgVector`, `.Qdrant`, `.SqlServer`, `.CosmosNoSQL`, `.InMemory`, etc.), even though `Microsoft.Extensions.VectorData.Abstractions` itself has been transferred out of the Semantic Kernel repo into `dotnet/extensions` and is fully independent of SK orchestration.
+> **Atualização de 2026-09-08 — a pegadinha mudou de forma.** Os conectores concretos **saíram** dos nomes `Microsoft.SemanticKernel.Connectors.*` e passaram a `CommunityToolkit.VectorData.*` (repositório `github.com/CommunityToolkit/AI`). Medido na API do nuget.org em 2026-09-08:
+>
+> | Pacote | Última versão | Publicada | Estável? |
+> |---|---|---|---|
+> | `Microsoft.SemanticKernel.Connectors.PgVector` | `1.74.0-preview` | 2026-03-20 | **Nunca teve versão estável**; parou aí |
+> | `CommunityToolkit.VectorData.PgVector` | **`1.0.1`** | **2026-08-31** | **Sim** |
+> | `CommunityToolkit.VectorData.InMemory` | `1.0.1` | 2026-08-31 | Sim |
+>
+> Os dois carregam o **mesmo título e a mesma descrição** ("Postgres (with pgvector extension) provider for Microsoft.Extensions.VectorData"), trocando apenas o autor — *"by Semantic Kernel"* → *"by the .NET Community Toolkit"*. É a mesma peça, com outro dono e outro nome.
+>
+> **Use `CommunityToolkit.VectorData.PgVector` 1.0.1.** O pacote com nome de Semantic Kernel é caminho morto: última versão em março de 2026, e preview.
+>
+> *Fronteira do que foi medido:* a substituição acima é medida (existência, versões, datas, título e descrição, apurados na API do nuget.org em 2026-09-08). Que a página do NuGet **exiba um aviso de rename** não foi confirmado nem pelo `.nuspec` da 1.74.0-preview nem pelos metadados de deprecação da registration API — a afirmação aqui é a substituição, não o aviso.
+
+A pegadinha original — abaixo — continua valendo para **projeto legado** que ainda referencia o nome antigo, e para quem tropeça no nome ao ler código existente.
+
+The concrete vector-store **connectors** — the packages that actually implement `VectorStoreCollection` against a real backend — **used to** ship under `Microsoft.SemanticKernel.Connectors.*` package names (`Microsoft.SemanticKernel.Connectors.PgVector`, `.Qdrant`, `.SqlServer`, `.CosmosNoSQL`, `.InMemory`, etc.), even though `Microsoft.Extensions.VectorData.Abstractions` itself has been transferred out of the Semantic Kernel repo into `dotnet/extensions` and is fully independent of SK orchestration.
 
 Microsoft's own docs are explicit about this:
 
@@ -45,28 +61,36 @@ Microsoft's own docs are explicit about this:
 
 ## Maturidade atual (verificado 2026-07-06)
 
-| Package | Status |
-|---------|--------|
-| `Microsoft.Extensions.VectorData.Abstractions` | **GA** |
-| `Microsoft.Extensions.AI` / `Microsoft.Extensions.AI.Abstractions` | **GA** |
-| `Microsoft.SemanticKernel.Connectors.PgVector` (Postgres/pgvector connector) | **Prerelease** (1.74.0-preview, requires `--prerelease`) |
-| `Microsoft.SemanticKernel.Connectors.InMemory` / other connectors | Verify current status via context7/NuGet before adding — connector GA timing lags the abstractions package |
-| `Microsoft.Extensions.DataIngestion` | **Preview** (10.0.1-preview.1.25571.5) |
+> Tabela **reapurada em 2026-09-08** na API do nuget.org. Cada linha traz a versão exata e a data — nenhum destes pacotes está no `framework/ai-pin.json`, então a data de apuração é o que dá validade ao número.
+
+| Package | Versão (apurada 2026-09-08) | Status |
+|---------|------------------------------|--------|
+| `Microsoft.Extensions.VectorData.Abstractions` | **10.9.0** (publicada 2026-08-11) | **GA** — é a camada de abstração |
+| `Microsoft.Extensions.AI` / `Microsoft.Extensions.AI.Abstractions` | **10.9.0** (no ai-pin) | **GA** |
+| `CommunityToolkit.VectorData.PgVector` (Postgres/pgvector connector) | **1.0.1** (publicada 2026-08-31) | **Estável** — é o conector recomendado hoje |
+| `CommunityToolkit.VectorData.InMemory` / demais conectores | **1.0.1** (2026-08-31) | Estável; confira cada um antes de adicionar |
+| `Microsoft.SemanticKernel.Connectors.PgVector` | `1.74.0-preview` (2026-03-20) | **Caminho morto** — nunca teve versão estável e não avança desde março/2026 |
+| `Microsoft.Extensions.DataIngestion` | **`10.9.0-preview.1.26411.16`** | **Preview** — sem versão estável |
 
-Preview packages are subject to breaking API changes before GA (see the May 2025 rename `PostgresVectorStoreRecordCollection` → `PostgresCollection` as precedent).
+> **Cuidado com o número que o conector declara.** `CommunityToolkit.VectorData.PgVector` 1.0.1 depende de `Microsoft.Extensions.VectorData.Abstractions` **10.8.2** — esse é o **piso da dependência**, não a versão corrente da abstração, que é 10.9.0. Citar 10.8.2 como "a versão do VectorData" é ler o `.nuspec` do conector como se fosse o do pacote.
+
+Preview packages are subject to breaking API changes before GA (see the rename `PostgresVectorStoreRecordCollection` → `PostgresCollection` as precedent).
 
 ---
 
 ## Decision matrix — custom pgvector vs VectorData
 
+**O critério, em uma frase:** a abstração se paga quando **a troca de store é plausível**; o SQL cru se paga quando **já funciona e é testado**. Nada aqui manda migrar o que está de pé.
+
 | Situation | Use |
 |-----------|-----|
-| Default production RAG on Neon/Postgres (this framework's default stack) | **`ai-agents-rag-custom-pgvector`** — GA-quality, zero preview dependencies, framework-owned raw SQL, already the checklisted default |
-| Project needs genuine portability across >1 vector backend (e.g., a client contract requires swapping Postgres for Qdrant or Azure AI Search later) | `Microsoft.Extensions.VectorData` with the relevant connector — document the choice in `decisions.md` |
-| Prototyping, tests, or demos where an in-memory GA-quality store is enough | `Microsoft.Extensions.VectorData` + an in-memory/SQLite connector |
-| Team explicitly accepts a preview dependency for the Postgres connector today | Allowed, but record the acceptance + a revisit-at-GA note in `decisions.md`; do not silently swap the default |
+| Default production RAG on Neon/Postgres (this framework's default stack), **already implemented and tested** | **`ai-agents-rag-custom-pgvector`** — framework-owned raw SQL, zero external connector, already the checklisted default. **Não se migra o que funciona** (item D4 da elevação-9) |
+| **Projeto novo** onde a escolha do store ainda não foi cravada, e trocá-lo depois deve custar pouco | `Microsoft.Extensions.VectorData.Abstractions` 10.9.0 + `CommunityToolkit.VectorData.PgVector` 1.0.1 — hoje **ambos estáveis**, o que remove o argumento "é preview" que existia em julho/2026 |
+| Project needs genuine portability across >1 vector backend (a client contract requires swapping Postgres for Qdrant or Azure AI Search later) | `Microsoft.Extensions.VectorData` + o conector correspondente — document the choice in `decisions.md` |
+| Prototyping, tests, or demos where an in-memory store is enough | `CommunityToolkit.VectorData.InMemory` 1.0.1 |
+| Ingestão em pipeline (reader → chunker → writer) hoje | Só com `Microsoft.Extensions.DataIngestion`, que **continua preview**: registre a aceitação e um lembrete de revisitar no GA |
 
-Do not migrate the existing `ai-agents-rag-custom-pgvector` implementation to the preview PgVector connector as a default — that would trade a working, GA-quality, framework-owned implementation for an unstable dependency, contradicting this framework's no-preview-by-default stance (see `ai-agents-setup` §1).
+Do not migrate the existing `ai-agents-rag-custom-pgvector` implementation to VectorData as a default — that would rewrite a working, tested, framework-owned implementation for no functional gain. **O que mudou desde a verificação anterior:** o argumento *"o conector é preview"* **caiu** (o `CommunityToolkit` é estável desde 2026-08-31); o argumento *"não se reescreve o que funciona"* **permanece**, e é ele que sustenta o default hoje.
 
 ---
 
@@ -138,9 +162,11 @@ This maps conceptually onto the existing custom pattern: `IngestionDocumentReade
 
 | Anti-pattern | Why it's wrong | Right way |
 |--------------|----------------|-----------|
-| Refusing to add `Microsoft.SemanticKernel.Connectors.PgVector` because of the "Forbidden: Microsoft.SemanticKernel.*" rule | The rule targets SK orchestration, not VectorData connectors — see the naming-trap section above | Read this standard's exception note before treating any `Microsoft.SemanticKernel.Connectors.*` package as forbidden |
-| Migrating the working custom pgvector implementation to VectorData "because it's official" | The Postgres connector is still prerelease — trades a stable implementation for an unstable one with no functional gain by default | Keep `ai-agents-rag-custom-pgvector` as the default; adopt VectorData only per the decision matrix |
-| Treating `Microsoft.Extensions.DataIngestion` as production-ready | It ships as `10.0.1-preview.1` — breaking changes are expected before GA | Track it for future adoption; do not wire it into a shipped feature today |
+| Refusing to add a VectorData connector because of the "Forbidden: Microsoft.SemanticKernel.*" rule | The rule targets SK orchestration, not VectorData connectors — see the naming-trap section above | Read this standard's exception note before treating any `Microsoft.SemanticKernel.Connectors.*` package as forbidden |
+| **Adding `Microsoft.SemanticKernel.Connectors.PgVector` in a new project** | Caminho morto: `1.74.0-preview` de 2026-03-20, sem versão estável | `CommunityToolkit.VectorData.PgVector` 1.0.1 |
+| **Citar `Microsoft.Extensions.VectorData.Abstractions` 10.8.2 como "a versão atual"** | 10.8.2 é o **piso da dependência** declarado pelo conector; a corrente é 10.9.0 | Ler a versão no pacote da abstração, não no `.nuspec` de quem depende dela |
+| Migrating the working custom pgvector implementation to VectorData "because it's official" | Reescreve uma implementação testada sem ganho funcional. Note que o motivo mudou: já **não** é mais "porque é preview" | Keep `ai-agents-rag-custom-pgvector` as the default; adopt VectorData per the decision matrix |
+| Treating `Microsoft.Extensions.DataIngestion` as production-ready | Continua preview em 2026-09-08 (`10.9.0-preview.1.26411.16`), sem versão estável | Track it for future adoption; do not wire it into a shipped feature today |
 | Importing `Microsoft.SemanticKernel` (the core orchestration package) to "just get the vector store types" | Pulls in the full SK orchestration surface this framework has deliberately moved away from | Import only `Microsoft.Extensions.VectorData.Abstractions` + the specific `*.Connectors.*` package needed |
 
 ---
@@ -150,7 +176,9 @@ This maps conceptually onto the existing custom pattern: `IngestionDocumentReade
 - [ ] If `Microsoft.SemanticKernel.Connectors.*` appears in a `.csproj`, it is used only for `VectorStoreCollection`/`VectorStore` types — no `Kernel`, `KernelFunction`, or `ChatHistory` usage anywhere in the project.
 - [ ] No plain `Microsoft.SemanticKernel` (core) package reference.
 - [ ] If VectorData was chosen over custom pgvector, the reason is recorded in `decisions.md` per the decision matrix.
-- [ ] If a preview package (`Microsoft.SemanticKernel.Connectors.*` or `Microsoft.Extensions.DataIngestion`) was adopted, `decisions.md` records the preview-acceptance and a revisit-at-GA note.
+- [ ] No new `Microsoft.SemanticKernel.Connectors.*` reference — new work uses `CommunityToolkit.VectorData.*`.
+- [ ] If a preview package (`Microsoft.Extensions.DataIngestion`, or any `*-preview` connector) was adopted, `decisions.md` records the preview-acceptance and a revisit-at-GA note.
+- [ ] Every VectorData/ingestion `PackageReference` carries an exact version — these packages are **not** in `framework/ai-pin.json`, so the project's own `decisions.md` (or a comment) states when the version was checked.
 - [ ] Embedding model/dimensions consistent between the `VectorStoreVector(N)` attribute and the chosen embedding model.
 
 ---
@@ -164,7 +192,9 @@ This maps conceptually onto the existing custom pattern: `IngestionDocumentReade
 - Data ingestion - .NET | Microsoft Learn: https://learn.microsoft.com/en-us/dotnet/ai/conceptual/data-ingestion
 - AI and Vector Data Extensions GA announcement: https://devblogs.microsoft.com/dotnet/ai-vector-data-dotnet-extensions-ga/
 - Introducing Data Ingestion Building Blocks (Preview): https://devblogs.microsoft.com/dotnet/introducing-data-ingestion-building-blocks-preview/
+- Vector stores overview: https://learn.microsoft.com/en-us/dotnet/ai/vector-stores/overview
+- `CommunityToolkit.VectorData.*` — repositório https://github.com/CommunityToolkit/AI (apurado 2026-09-08)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/vector-data-extensions.md v1.0 (2026-07-06)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/vector-data-extensions.md v2.0 (2026-09-08)*