@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

package/framework/standards/ai-agents/providers/model-registry.md

@@ -2,16 +2,16 @@
 
 > **Scope:** stacks=["dotnet"]
 > **Layer:** 0 (always-load via persona maf-expert)
-> **Keywords:** model registry, provider agnostic, model alias, IChatClient factory, multi-model, model selection, model config
+> **Keywords:** model registry, provider agnostic, model alias, IChatClient factory, multi-model, model selection, model config, api per alias, responses vs chat, reasoning effort
 > **Read by Claude in:** plan (cita este standard quando feature menciona >1 modelo ou multi-provider) + implement (copia o template ModelRegistry.cs e gera config no projeto)
 
-**Verified against:** MAF 1.0 GA + tier list research (2026-05-18). Last-verified: 2026-05-19.
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 + OpenAI 2.13.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Providers/ModelRegistry.cs` e `.../Providers/ModelAlias.cs` e `.../Agents/AgentApi.cs`. Nomes de tipo do `Microsoft.Extensions.AI` e do `OpenAI` medidos por reflexão sobre as assemblies do pin em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
 ## Pattern
 
-The project consuming morph-spec maintains a **single JSON file** mapping aliases (`text-default`, `vision`, `reasoning`, etc.) to `{ provider, model, options }`. Agents reference aliases — never hardcoded model strings. Switching provider or model is a one-file change.
+The project consuming morph-spec maintains a **single JSON file** mapping aliases (`text-default`, `vision`, `reasoning`, etc.) to `{ provider, model, api, options }`. Agents reference aliases — never hardcoded model strings. Switching provider or model is a one-file change.
 
 ```
 Standard (this file, in framework) — explains the pattern + canonical schema
@@ -28,17 +28,38 @@ Project (consumer) — config/model-registry.json + src/.../ModelRegistry.cs
 // config/model-registry.json — IN THE PROJECT (not in framework)
 {
   "$schema": "./model-registry.schema.json",
-  "version": "1.0",
+  "version": "2.0",
   "defaultAlias": "text-default",
   "aliases": {
-    "text-default":  { "provider": "openai",    "model": "gpt-4o-mini",             "options": { "temperature": 0.7 } },
-    "text-heavy":    { "provider": "openai",    "model": "gpt-4o",                  "options": { "temperature": 0.5 } },
-    "reasoning":     { "provider": "openai",    "model": "o3-mini",                 "options": { "reasoningEffort": "medium" } },
-    "long-form":     { "provider": "anthropic", "model": "claude-sonnet-4-6",       "options": {} },
-    "vision":        { "provider": "google",    "model": "gemini-2.5-flash",        "options": {} },
-    "embeddings":    { "provider": "openai",    "model": "text-embedding-3-small",  "options": { "dimensions": 1536 } },
-    "transcription": { "provider": "openai",    "model": "whisper-1",               "options": {} },
-    "local-dev":     { "provider": "ollama",    "model": "llama3.2:3b",             "options": { "endpoint": "http://localhost:11434/v1" } }
+    // `api` omitted → "responses" (the house default; see §API per alias)
+    "text-default":  { "provider": "openai", "model": "gpt-4o-mini", "options": { "temperature": 0.7 } },
+    "text-heavy":    { "provider": "openai", "model": "gpt-4o",      "options": { "temperature": 0.5 } },
+
+    // Reasoning alias: NO temperature. See §temperature × reasoning.
+    "reasoning": {
+      "provider": "openai",
+      "model": "gpt-5.5",
+      "api": "responses",
+      "options": { "reasoningEffort": "medium" }
+    },
+
+    // Chat Completions is opt-in, in writing, with the constraint declared.
+    "legacy-chat": {
+      "provider": "openai",
+      "model": "gpt-5.5",
+      "api": "chat",
+      "options": {},
+      "constraints": {
+        "toolCallingRequiresReasoningEffortNone": true,
+        "provenance": "developers.openai.com/api/docs/guides/migrate-to-responses, lido 2026-09-08"
+      }
+    },
+
+    "long-form":     { "provider": "anthropic", "model": "claude-sonnet-4-6",      "options": {} },
+    "vision":        { "provider": "google",    "model": "gemini-2.5-flash",       "options": {} },
+    "embeddings":    { "provider": "openai",    "model": "text-embedding-3-small", "options": { "dimensions": 1536 } },
+    "transcription": { "provider": "openai",    "model": "whisper-1",              "options": {} },
+    "local-dev":     { "provider": "ollama",    "model": "llama3.2:3b",            "options": { "endpoint": "http://localhost:11434/v1" } }
   },
   "fallback": {
     "text-default": "anthropic/claude-haiku-4-5",
@@ -52,27 +73,126 @@ Project (consumer) — config/model-registry.json + src/.../ModelRegistry.cs
 **Field semantics:**
 - `provider`: SDK family — one of `openai`, `google`, `anthropic`, `ollama` (first-class). `azure-openai` is supported as an opt-in branch (see §providers).
 - `model`: model id for that provider.
-- `options`: provider-specific extras (temperature, reasoning effort, `endpoint` for Ollama, etc.).
+- `api`: **the protocol this alias speaks** — `responses` or `chat`. Omitting it means `responses`. See §API per alias.
+- `options`: per-request extras. `temperature`, `topP`, `maxOutputTokens`, `seed`, `stopSequences`, `toolMode`, `reasoningEffort`, `serviceTier`, plus `endpoint` for Ollama. **`temperature` and `reasoningEffort` never appear in the same alias** — see §temperature × reasoning.
+- `constraints`: declared limits of this alias (`toolCallingRequiresReasoningEffortNone`, `temperatureUnsupported`) — **each one requires `provenance`**, the document and date it came from. A limit with no source is folklore with the force of code.
 - `fallback`: when the primary provider fails (rate limit, outage), switch to this alias. Format `provider/model`.
 
 ---
 
+## API per alias — `responses` vs `chat`
+
+**Every alias declares which protocol it speaks.** This is the field the v1 schema did not have, and its absence is why "which API does this agent talk to?" used to be answered by reading a conditional in the middle of the client factory.
+
+| Value | Meaning | When |
+|---|---|---|
+| `responses` (**default when omitted**) | OpenAI **Responses API** | New work. `default(AgentApi)` is `Responses` on purpose |
+| `chat` | OpenAI **Chat Completions** | Opt-in, written by a human, for broad model compatibility or an existing integration |
+
+**Why Responses is the default**, in two documented facts:
+
+1. Microsoft Learn, *Agent Framework → model providers → OpenAI* (`ms.date` 2026-09-03), verbatim: *"Responses is the recommended primary client when available"*, with a tool matrix in which Chat Completions loses **Code Interpreter, File Search and Hosted MCP**.
+2. OpenAI, *Migrate to the Responses API* (developers.openai.com/api/docs/guides/migrate-to-responses, lido 2026-09-08), verbatim: *"While Chat Completions remains supported, Responses is recommended for all new projects."*
+
+**Providers that expose a single protocol (Google, Ollama, Anthropic) ignore the field.** The enum describes the choice **between the two OpenAI protocols**; writing `"api": "chat"` on an Ollama alias would suggest a choice that provider does not offer. They therefore omit `api` and fall into `responses`, which the registry treats as "no protocol decision to make here". What must **not** happen is reaching an OpenAI-compatible endpoint (Ollama, gateway) through the Responses path: the Responses API is OpenAI's, not the compatible protocol's — the provider branch in `ModelRegistry.GetChatClient` builds a Chat Completions client for those, regardless of the field.
+
+> Measured: `Morph.AiKit.Agents.AgentApi` has `Responses = 0` so that `default(AgentApi)` is Responses, and `ModelRegistry.ReadApi` returns `AgentApi.Responses` when `api` is absent and throws naming the alias for any value other than `responses`/`chat`. `AgentSpec.ResolveApi(aliasApi) => Api ?? aliasApi` keeps the precedence between spec and registry in exactly one place.
+
+---
+
+## temperature × reasoning — mutually exclusive per alias
+
+**Rule:** an alias that carries `reasoningEffort` does **not** carry `temperature`. The rule has **two different origins, and the standard labels each one** — because they do not carry the same weight.
+
+### Origin 1 — documented
+
+OpenAI, *Migrate to the Responses API* (developers.openai.com/api/docs/guides/migrate-to-responses, lido 2026-09-08), verbatim:
+
+> *"Starting with GPT-5.4, Chat Completions does not support tool calling with `reasoning_effort` values other than `none`."*
+
+Read it narrowly, because it **is** narrow: the restriction needs **four** facts at once — protocol `chat`, tools present, an effort actually sent, and that effort ≠ `none`. It is *not* "reasoning models reject tools". Direct consequence: **a reasoning alias that uses tools needs `api: responses`.**
+
+### Origin 2 — measured in the field, no primary source
+
+*"Reasoning models reject `temperature != 1` when tools are present."* This is **measured in production**, not documented: GHLBrain's `ToolAgentRunner.cs:35-38` strips temperature for that path, recorded in `docs/specs/elevacao-9/brutos/scan-ghlbrain.md:106`, and corroborated by third parties (issues on `openai-python` and LibreChat). **The 2026-09-08 research did not find a primary OpenAI sentence stating it.**
+
+So it lives in the schema as a **per-alias flag with mandatory provenance** (`constraints.temperatureUnsupported` + `constraints.provenance`), never as a universal rule hardcoded in the registry. Whoever turns it on is asserting it for one specific model and writing where they got it from.
+
+> Measured: `ModelAliasConstraints.ValidateProvenance` refuses to load an alias with a flag set and no `provenance`, and `ModelAlias.CheckRequest` returns a Result (never an exception) listing each violation **with its provenance attached**.
+
+### Reasoning effort values, by model, dated
+
+| Model | Accepted efforts | Source (lido 2026-09-08) |
+|---|---|---|
+| `gpt-5.5` | `none`, `low`, `medium` (default), `high`, `xhigh` | developers.openai.com/api/docs/models/gpt-5.5 |
+| `gpt-5.6` | the above **plus `max`**, and introduces `reasoning.mode` (`standard` / `pro`) | developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6 |
+
+---
+
+## How this reaches .NET
+
+**The native path is confirmed** — measured by reflection over `Microsoft.Extensions.AI.Abstractions` 10.9.0 on 2026-09-08, and compiled by the ai-kit:
+
+```csharp
+// Microsoft.Extensions.AI 10.9.0 — measured surface
+//   ChatOptions.Reasoning : ReasoningOptions?
+//   ReasoningOptions { ReasoningEffort? Effort; ReasoningOutput? Output; }
+//   enum ReasoningEffort { None=0, Low=1, Medium=2, High=3, ExtraHigh=4 }
+var options = new ChatOptions
+{
+    ModelId = alias.Model,
+    Reasoning = new ReasoningOptions { Effort = ReasoningEffort.Medium },
+};
+```
+
+**Escape hatch, and when it is still needed.** The M.E.AI enum has five members; the provider's own ladder is wider (`gpt-5.6` adds `max`, and `reasoning.mode`). For a value the enum cannot express, go through `ChatOptions.RawRepresentationFactory` and the provider type:
+
+```csharp
+// OpenAI 2.13.0 — measured surface
+//   CreateResponseOptions.ReasoningOptions : ResponseReasoningOptions
+//   ResponseReasoningOptions.ReasoningEffortLevel : ResponseReasoningEffortLevel?
+//   ResponseReasoningEffortLevel = { None, Minimal, Low, Medium, High }   ← no xhigh/max in 2.13.0
+#pragma warning disable OPENAI001   // still required — see §OPENAI001
+options.RawRepresentationFactory = _ => new CreateResponseOptions
+{
+    ReasoningOptions = new ResponseReasoningOptions
+    {
+        ReasoningEffortLevel = ResponseReasoningEffortLevel.High,
+    },
+};
+#pragma warning restore OPENAI001
+```
+
+**Honest limit:** `xhigh` and `max` are documented by OpenAI for `gpt-5.5`/`gpt-5.6` but are **not present in the `OpenAI` 2.13.0 SDK's `ResponseReasoningEffortLevel`** (measured). Sending them today means a raw JSON patch, not a typed member. Confirm against the installed package before promising a project the wider ladder.
+
+### `OPENAI001`
+
+**Measured, not inferred:** `OpenAI.Responses.ResponsesClient` and `OpenAI.Responses.CreateResponseOptions` still carry `[Experimental("OPENAI001")]` in **OpenAI 2.13.0** (reflection over the pinned assembly, 2026-09-08). Code that touches the Responses client types directly still needs `#pragma warning disable OPENAI001` (or `<NoWarn>OPENAI001</NoWarn>`). `OpenAI.Chat.ChatClient` carries no such attribute.
+
+Going through `Microsoft.Extensions.AI` (`IChatClient`) or the MAF (`AIAgent`) keeps the diagnostic out of project code — the bridge package absorbs it. That is a reason to prefer the abstraction, not merely a style preference.
+
+---
+
 ## Providers (first-class)
 
 > **This section is the single source of truth for provider SDKs.** Provider SDKs change names/versions often — keep this section verified with a date; templates stay stable.
 
-| Provider | `provider` value | NuGet SDK (LAST-VERIFIED 2026-05-19) | Notes |
-|----------|------------------|--------------------------------------|-------|
-| **OpenAI** | `openai` | `OpenAI` 2.* | `new ChatClient(model, apiKey).AsIChatClient()` |
-| **Ollama** | `ollama` | `OpenAI` 2.* (OpenAI-compatible endpoint) | Same `ChatClient` with custom `Endpoint` + dummy key |
-| **Google Gemini** | `google` | Confirm current SDK on NuGet before use | Adapt provider client to `IChatClient` |
-| **Anthropic Claude** | `anthropic` | Confirm current SDK on NuGet before use | Adapt provider client to `IChatClient` |
-| **Azure OpenAI** (opt-in, not default) | `azure-openai` | `Azure.AI.OpenAI` 2.* + `Azure.Identity` | Add only when a client requires data residency |
+| Provider | `provider` value | NuGet SDK (apurado 2026-09-08) | `api` | Notes |
+|----------|------------------|-------------------------------|-------|-------|
+| **OpenAI** | `openai` | `OpenAI` **2.13.0** (pin) + `Microsoft.Extensions.AI.OpenAI` **10.9.0** (fora do pin, apurado 2026-09-08) | `responses` (default) / `chat` | `new OpenAIClient(key).GetResponsesClient().AsIChatClient("<model>")` |
+| **Ollama** | `ollama` | `OpenAI` **2.13.0** (OpenAI-compatible endpoint) | ignora o campo | Same `ChatClient` with custom `Endpoint` + dummy key. **Never** through the Responses path |
+| **Google Gemini** | `google` | `Google.GenAI` **1.21.0** (pin) | ignora o campo | Adapt provider client to `IChatClient` |
+| **Anthropic Claude** | `anthropic` | Confirm current SDK on NuGet before use | ignora o campo | Adapt provider client to `IChatClient` |
+| **Azure OpenAI** (opt-in, not default) | `azure-openai` | `Azure.AI.OpenAI` + `Azure.Identity` — confirm exact versions on NuGet before use | segue o OpenAI | Add only when a client requires data residency |
+
+> **Restore trap, measured 2026-09-08:** `Microsoft.Extensions.AI.OpenAI` 10.9.0 declares `OpenAI (>= 2.12.0 && < 2.13.0)`. Pairing it with the pinned `OpenAI` 2.13.0 emits **NU1608** on restore. Either pin `OpenAI` to 2.12.x alongside the bridge, or accept the warning knowingly and write the decision in `decisions.md`. Do not discover this in CI.
+
+**No floating ranges.** Every `PackageReference` above is an exact version. A floating `2.*` on a weekly-cadence SDK is how ProspectPRO bought a `MissingMethodException` on the Responses API **after paying for the call** (`docs/specs/elevacao-9/brutos/scan-prospectpro.md:55`).
 
 **Adding a provider branch:** the `ModelRegistry.cs` template implements `openai` + `ollama`. To add `google`, `anthropic`, or `azure-openai`:
 1. Confirm the current NuGet SDK — community SDKs evolve; check NuGet/context7 before coding.
 2. Add a `case "<provider>":` branch in `ModelRegistry.GetChatClient`'s switch, following the `openai`/`ollama` pattern.
-3. Add the SDK `PackageReference` to the project's `.csproj`.
+3. Add the SDK `PackageReference` to the project's `.csproj`, with an **exact** version.
 4. The branch returns an `IChatClient`. If the SDK doesn't expose `IChatClient` natively, wrap it with an adapter.
 
 **Direct models only:** never use a hosted agent service. Every provider above is reached as a direct model.
@@ -82,17 +202,21 @@ Project (consumer) — config/model-registry.json + src/.../ModelRegistry.cs
 ## Implementation pattern
 
 ```csharp
-// WRONG — hardcoded model + provider
+// WRONG — hardcoded model + provider, and no protocol decision anywhere
 var agent = new ChatClient("gpt-4o-mini", apiKey)
     .AsIChatClient()
     .AsAIAgent(instructions: prompt);
 
-// RIGHT — alias-based, provider-agnostic
+// RIGHT — alias-based, provider-agnostic; the alias carries provider, model AND api
 var agent = _modelRegistry.GetChatClient("text-default")
     .AsAIAgent(instructions: prompt);
 ```
 
-The `ModelRegistry` class in the project owns the mapping. See template `templates/code/dotnet/ai-agents/ModelRegistry.cs.template`.
+The `ModelRegistry` class in the project owns the mapping. See template `templates/code/dotnet/ai-agents/ModelRegistry.cs.template`, and the compiling reference implementation in `templates/dotnet/ai-kit/src/Morph.AiKit/Providers/`.
+
+**One client per alias, memoized.** A provider client owns a connection pool and an HTTP handler; rebuilding it per call is how socket exhaustion usually starts. `ModelRegistry.GetChatClient` calls the factory once per alias and hands back the same instance afterwards.
+
+**Failure at load time, never as control flow.** Invalid document, alias with no pricing decision, constraint without provenance: all of it throws during composition, naming the alias and the field — never as a null that crosses three layers and shows up as a zeroed cost in a report.
 
 ---
 
@@ -102,26 +226,26 @@ When a task says "register the X agent" and the project has >1 model or >1 provi
 
 1. Read this standard.
 2. Copy `templates/code/dotnet/ai-agents/ModelRegistry.cs.template` to `src/.../ModelRegistry.cs` in the project. Substitute placeholders.
-3. Copy `templates/code/dotnet/ai-agents/model-registry.json.template` to `config/model-registry.json`. Adjust aliases to project needs.
+3. Copy `templates/code/dotnet/ai-agents/model-registry.json.template` to `config/model-registry.json`. Adjust aliases to project needs, and **declare `api` on every OpenAI alias that is not Responses**.
 4. Wire `ModelRegistry` into DI (see `AgentBootstrap.cs.template`).
 5. Future agents reference `_modelRegistry.GetChatClient(alias)`.
 
 ---
 
-## Recommended aliases & models (orientativo — maio/2026)
+## Recommended aliases & models (orientativo — setembro/2026)
 
 > Tabela orientativa. Actual values live in the project's `model-registry.json`. Models evolve fast.
 
-| Alias | Provider sugerido | Modelo (maio/2026) | Use case |
-|-------|-------------------|--------------------|----------|
-| `text-default` | openai | gpt-4o-mini | Geração padrão de texto |
-| `text-heavy` | openai / anthropic | gpt-4o / claude-sonnet-4-6 | Análise complexa |
-| `reasoning` | openai | o3-mini | Decisões, planejamento, math |
-| `long-form` | anthropic | claude-sonnet-4-6 | Escrita longa, análise de documento |
-| `vision` | google / openai | gemini-2.5-flash / gpt-4o | Image → Text |
-| `embeddings` | openai | text-embedding-3-small | RAG, similarity |
-| `transcription` | openai | whisper-1 | Audio → Text |
-| `local-dev` | ollama | llama3.2:3b | Dev local, sem custo |
+| Alias | Provider sugerido | Modelo (setembro/2026) | `api` | Use case |
+|-------|-------------------|------------------------|-------|----------|
+| `text-default` | openai | gpt-4o-mini | responses | Geração padrão de texto |
+| `text-heavy` | openai / anthropic | gpt-4o / claude-sonnet-4-6 | responses | Análise complexa |
+| `reasoning` | openai | gpt-5.5 (`reasoningEffort`, **sem** `temperature`) | responses | Decisões, planejamento, math |
+| `long-form` | anthropic | claude-sonnet-4-6 | — | Escrita longa, análise de documento |
+| `vision` | google / openai | gemini-2.5-flash / gpt-4o | responses | Image → Text |
+| `embeddings` | openai | text-embedding-3-small | — | RAG, similarity |
+| `transcription` | openai | whisper-1 | — | Audio → Text |
+| `local-dev` | ollama | llama3.2:3b | — (Chat Completions no fio) | Dev local, sem custo |
 
 ---
 
@@ -130,6 +254,10 @@ When a task says "register the X agent" and the project has >1 model or >1 provi
 | Anti-pattern | Why | Right way |
 |--------------|-----|-----------|
 | Hardcode `"gpt-4o-mini"` in agent code | Switching model = grep + replace | Use `_modelRegistry.GetChatClient("text-default")` |
+| Alias com `temperature` **e** `reasoningEffort` | Os dois não convivem no mesmo modelo; um dos dois será silenciosamente ignorado ou rejeitado | Um alias de raciocínio sem `temperature`; se o limite for do modelo, declare em `constraints` **com `provenance`** |
+| `constraints` sem `provenance` | Um limite sem fonte é folclore com força de código | Escreva o documento e a data; o registry recusa a carga sem isso |
+| Alias OpenAI sem decidir `api` quando o caminho é Chat Completions | Ninguém sabe qual protocolo o agente fala até ler o factory | Omitido = `responses`; Chat Completions exige `"api": "chat"` por escrito |
+| `PackageReference` com faixa flutuante (`2.*`, `1.0.*`) | SDK de cadência semanal quebra em produção depois de a chamada ser paga | Versão exata; pacote fora do `ai-pin.json` leva a data de apuração |
 | Put `model-registry.json` in `.morph/` | `.morph/framework` is framework-only; `.morph/config/config.json` is reserved for morph-spec metadata | Put it in `config/` of the project |
 | Different `ModelRegistry` class per agent | Defeats the purpose | One class per project, singleton in DI |
 | Use a hosted agent service to "simplify" | Hosted lags 6-9 months, removes control | Always direct models |
@@ -139,20 +267,27 @@ When a task says "register the X agent" and the project has >1 model or >1 provi
 
 ## Checklist (verifiable by morph-eval)
 
-- [ ] Project has `config/model-registry.json` (or declared equivalent).
+- [ ] Project has `config/model-registry.json` (or declared equivalent), `version` `2.0`.
 - [ ] Project has a `ModelRegistry` class registered as singleton in DI.
+- [ ] Every OpenAI alias either omits `api` (→ `responses`) or declares `"api": "chat"` explicitly.
+- [ ] No alias carries `temperature` and `reasoningEffort` at the same time.
+- [ ] Every `constraints` block has a non-empty `provenance` with a document and a date.
 - [ ] No agent code has hardcoded model strings — `grep -rE 'gpt-[0-9]|claude-|gemini-|whisper-' src/` matches only `ModelRegistry.cs`.
 - [ ] Aliases used in agent code exist in `model-registry.json`.
+- [ ] No `PackageReference` in the project uses a floating range for an AI SDK.
 
 ---
 
 ## References
 
-- `ai-agents-setup` — provider SDKs
+- `ai-agents-setup` — provider SDKs, Responses vs Chat Completions setup
+- `ai-agents-structured-output` — `ResponseFormat` and what else goes into `ChatOptions`
+- `ai-agents-service-tier-flex` — `serviceTier` in `options`
+- Reference implementation (compiles against the pin): `templates/dotnet/ai-kit/src/Morph.AiKit/Providers/`
 - Template: `templates/code/dotnet/ai-agents/ModelRegistry.cs.template`
 - Template: `templates/code/dotnet/ai-agents/model-registry.json.template`
 - Template: `templates/code/dotnet/ai-agents/AgentBootstrap.cs.template`
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/providers/model-registry.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/providers/model-registry.md v2.0 (2026-09-08)*

package/framework/standards/ai-agents/rag-custom-pgvector.md

@@ -2,10 +2,10 @@
 
 > **Scope:** stacks=["dotnet"]
 > **Layer:** 1 (on-keyword)
-> **Keywords:** rag, vector search, pgvector, embeddings, custom rag, retrieval, semantic search, knowledge base, RAG tool
+> **Keywords:** rag, vector search, pgvector, embeddings, custom rag, retrieval, semantic search, knowledge base, RAG tool, delta ingestion, incremental ingestion, lookup key
 > **Read by Claude in:** implement (when an agent needs to retrieve knowledge)
 
-**Verified against:** MAF 1.0 GA + Microsoft.Extensions.AI. Last-verified: 2026-05-19.
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08); `provado por templates/dotnet/ai-kit/src/Morph.AiKit/Rag/DeltaIngest.cs` **restrito à seção "Ingestão delta por lookup-key"** — é a única parte deste standard que o ai-kit compila. Todo o resto (pgvector, SQL, HNSW, embeddings, multi-tenant) é **verificação documental**; a versão e o status de `Microsoft.Extensions.DataIngestion` foram apurados no nuget.org em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
@@ -186,6 +186,65 @@ The agent decides autonomously when to call `VectorSearchTool.SearchAsync`. It r
 
 ---
 
+## Ingestão delta por lookup-key
+
+**O defeito que esta seção existe para matar está em produção e foi medido.** `KbStore.IngestAsync` do GHLBrain faz `DELETE … WHERE location_id AND source` e re-insere/re-embeda **tudo** numa transação (`docs/specs/elevacao-9/brutos/scan-ghlbrain.md:412`): 288 itens re-embedados a cada republish do catálogo, e uma **janela** entre o apagar e o gravar em que a busca não acha nada.
+
+### O contrato — uma função pura, sem I/O
+
+```csharp
+// Nada aqui toca banco, vetor ou arquivo. Quem APLICA o plano é o projeto,
+// que sabe qual é a sua transação — e é por isso que a idempotência da
+// ingestão pode ser provada sem subir infraestrutura nenhuma.
+public static DeltaPlan<T> Plan<T>(
+    IEnumerable<T> incoming,
+    Func<T, string> lookupKey,
+    Func<T, string> contentHash,
+    IReadOnlyDictionary<string, string> existingHashes);
+
+public sealed record DeltaPlan<T>(
+    IReadOnlyList<T> Added,        // chave não existia no acervo
+    IReadOnlyList<T> Updated,      // chave existia com OUTRO conteúdo
+    IReadOnlyList<string> Removed, // chaves no acervo que NÃO vieram na entrada — são chaves, não itens
+    IReadOnlyList<T> Unchanged)    // chave existia com o MESMO conteúdo
+{
+    public bool IsNoOp => Added.Count == 0 && Updated.Count == 0 && Removed.Count == 0;
+    public int WriteCount => Added.Count + Updated.Count + Removed.Count;
+}
+```
+
+`IsNoOp` **é a idempotência expressa como predicado**: replanejar a mesma entrada sobre o acervo que ela produziu tem de dar `true`. É o teste que separa "delta" de "delete-and-reinsert com passos extras".
+
+### As quatro regras que fazem o delta valer a pena
+
+1. **`Unchanged` não é re-embedado.** É a economia inteira. Num republish típico a lista grande é `Unchanged` e as outras três são curtas — e é exatamente isso que a ingestão anterior escondia.
+2. **`Removed` são as chaves presentes no acervo e ausentes do `incoming`.** Sem esse balde, conteúdo apagado na origem continua sendo devolvido pela busca.
+3. **O id continua determinístico** — `DeterministicUuid.V5(namespace, "{loc}:{source}:{idx}")` já é a prática — para que `Updated` seja **upsert**, não delete+insert. Delete+insert quebra referências e troca o id de um chunk que só mudou de texto.
+4. **Sem janela vazia: nunca apague tudo antes de gravar.** É literalmente o que faz a busca devolver vazio durante a reingestão. Aplique `Added`/`Updated` primeiro e só então `Removed`, dentro da mesma transação.
+
+### Chave duplicada no `incoming` é erro de entrada
+
+Duas linhas com a mesma lookup-key tornam o plano **não determinístico** (qual das duas vence?). O planejador **falha**, dizendo a chave e **as duas posições** em que ela apareceu — porque "chave X duplicada" sem posição manda procurar num corpus inteiro. Silenciar isso produz um acervo diferente a cada execução da mesma entrada.
+
+### A alternativa oficial, com o status honesto
+
+`Microsoft.Extensions.DataIngestion` é o pipeline oficial (`IngestionDocument` → `IngestionChunker<T>` → `VectorStoreWriter<T>`), com `VectorStoreWriterOptions.IncrementalIngestion` e deduplicação por `DocumentId`. Status apurado em 2026-09-08: **preview** — a versão mais recente no nuget.org é `10.9.0-preview.1.26411.16`, e **não existe versão estável**.
+
+**Ressalva medida, que muda a decisão:** o teste oficial da funcionalidade chama-se `IncrementalIngestion_WithManyRecords_DeletesAllPreExistingChunks`. A semântica é *apagar todos os chunks pré-existentes daquele documento antes de regravar* — o que **não** é o mesmo que "não re-embedar o que não mudou".
+
+| Objetivo | O que resolve |
+|---|---|
+| **Custo** (não pagar embedding do que não mudou) | O plano por hash acima |
+| **Higiene** (não deixar chunk órfão de uma versão anterior do documento) | O `VectorStoreWriter` com `IncrementalIngestion` |
+
+Os dois não competem; resolvem problemas diferentes. Adote o writer quando aceitar a dependência preview.
+
+### Item aberto, medido em campo
+
+**Threshold de similaridade e `k` por escopo ainda não têm regra.** Hoje o escopo institucional da base do GHLBrain roda **sem `LIMIT`** (`scan-ghlbrain.md:410`): a busca devolve tudo o que passa do threshold, e o custo do prompt varia com o tamanho da base. Definir `k` e o corte por escopo é trabalho pendente, não recomendação existente — registrado aqui para não ser reinventado como se fosse novo.
+
+---
+
 ## Multi-tenant
 
 Each tenant's knowledge is partitioned by `tenant_id`:
@@ -229,7 +288,11 @@ ALTER TABLE kb_embeddings ENABLE ROW LEVEL SECURITY;
 - [ ] No `Microsoft.SemanticKernel` references in the project.
 - [ ] Vector dimensions consistent between embedding model and `vector(N)` column definition.
 - [ ] RLS enabled on `kb_embeddings` (or equivalent app-level guard documented in `decisions.md`).
-- [ ] Re-indexing strategy documented when document content changes (content hash check).
+- [ ] Ingestion follows §*Ingestão delta por lookup-key*: a pure `Plan(...)` produces `Added`/`Updated`/`Removed`/`Unchanged`, and `Unchanged` is never re-embedded.
+- [ ] No `DELETE`-everything-then-reinsert: `Removed` is applied **after** `Added`/`Updated`, in the same transaction — there is no window where the search returns empty.
+- [ ] `Updated` is an **upsert** on a deterministic id, never delete+insert.
+- [ ] A duplicate lookup-key in the incoming set **fails** the ingestion, naming the key and both positions.
+- [ ] Replanning the same input over the store it produced yields `IsNoOp == true` (idempotence, as a test).
 
 ---
 
@@ -240,7 +303,9 @@ ALTER TABLE kb_embeddings ENABLE ROW LEVEL SECURITY;
 - `data-vector-search-rag-chunking` — chunk strategies per document type
 - `infrastructure-neon-pgvector` — extension setup, `UseVector()`, HNSW parameter tuning
 - `ai-agents-vector-data-extensions` — the official `Microsoft.Extensions.VectorData` abstraction, and when it's worth adopting instead of this custom implementation
+- Reference implementation of the delta planner (compiles against the pin): `templates/dotnet/ai-kit/src/Morph.AiKit/Rag/DeltaIngest.cs` + `DeltaPlan.cs`
+- `Microsoft.Extensions.DataIngestion` — https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.dataingestion.vectorstorewriteroptions (preview; versão apurada 2026-09-08)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/rag-custom-pgvector.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/rag-custom-pgvector.md v2.0 (2026-09-08)*

package/framework/standards/ai-agents/service-tier-flex.md

@@ -5,7 +5,7 @@
 > **Keywords:** service tier, flex tier, cost optimization, async tier, priority tier
 > **Read by Claude in:** implement
 
-**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.* (campo `service_tier` confirmado pela REST API; nome da propriedade C# marcado `// VERIFY:` — ver seção A API). Last-verified: 2026-05-19.
+**Verified against:** OpenAI 2.13.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08). **Verificação documental** da política de tiers (platform.openai.com/docs/guides/service-tiers, lido 2026-09-08), sem cláusula `provado por`: o ai-kit **referencia** o pacote `OpenAI` no `.csproj` — contrato de versão, régua = restore (`NU1102`) — mas **não o exercita**; não existe um único `using OpenAI` em `src/` (medido 2026-09-08), logo um rename de API não reprova a PR. Ver a tabela "Dois níveis de garantia" no README do kit. **O nome e o tipo da propriedade C# foram medidos por reflexão sobre a assembly `OpenAI` 2.13.0 em 2026-09-08**, e o marcador `// VERIFY` desta página foi RESOLVIDO por essa medição. Last-verified: 2026-09-08.
 
 ---
 
@@ -27,17 +27,23 @@ Use o service tier **flex** quando o agente roda em background, sem usuário agu
 ## A API
 
 > **AVISO:** service tier é **OpenAI-specific** — não é exposto no `Microsoft.Extensions.AI.ChatOptions`.
-> Para setar service tier, use o `ChatClient` direto (obtido do Model Registry ou da configuração).
-
-> ### ⚠️ Status de verificação da API .NET
->
-> **Confirmado pela REST API da OpenAI:** o campo é `service_tier`, com valores `"auto"`,
-> `"default"` e `"flex"`.
+> Para setar service tier, use o `ChatClient`/`ResponsesClient` direto (obtido do Model Registry ou da configuração).
 >
-> **A confirmar contra o pacote `OpenAI` 2.\* instalado** (marcado `// VERIFY:` no código):
-> o nome exato da propriedade C# em `ChatCompletionOptions` e se os valores são `string`
-> constants ou membros de um enum (ex.: `ChatServiceTier.Flex`). O context7 não retornou a
-> superfície de `ChatCompletionOptions` para batch/tier — confirme no IntelliSense antes de codar.
+> Isso foi **medido**, não suposto: `Microsoft.Extensions.AI.ChatOptions` 10.9.0 tem 20 propriedades e **nenhuma** delas é service tier (reflexão sobre `Microsoft.Extensions.AI.Abstractions` 10.9.0, 2026-09-08). O caminho por abstração é `ChatOptions.AdditionalProperties["service_tier"]` **combinado com** um `RawRepresentationFactory` que traduza o valor — sem essa tradução, a chave em `AdditionalProperties` não chega ao fio.
+
+### O tipo é um struct, não uma string — e não existe `priority`
+
+Medido na assembly `OpenAI` 2.13.0:
+
+| Superfície | Propriedade | Tipo | Valores |
+|---|---|---|---|
+| Chat Completions | `ChatCompletionOptions.ServiceTier` | `ChatServiceTier?` | `Auto`, `Default`, `Flex`, `Scale` |
+| Responses | `CreateResponseOptions.ServiceTier` | `ResponseServiceTier?` | `Auto`, `Default`, `Flex`, `Scale` |
+
+Duas correções contra a versão anterior deste standard:
+
+1. **`ServiceTier = "flex"` não compila.** O valor é `ChatServiceTier.Flex` (um struct de valores nomeados, no estilo dos "extensible enums" do SDK), não uma `string`.
+2. **`priority` não existe no SDK 2.13.0.** Os quatro valores expostos são `Auto`, `Default`, `Flex` e `Scale`. Se a conta tem tier prioritário contratado, isso não aparece como membro tipado aqui — e este standard não vai fingir que aparece.
 
 ---
 
@@ -58,9 +64,7 @@ ChatClient chatClient = new(model, new ApiKeyCredential(apiKey));
 
 ChatCompletionOptions flexOptions = new()
 {
-    // VERIFY nome da propriedade e tipo do valor — string "flex" ou enum (ChatServiceTier.Flex).
-    // Ver "Status de verificação da API .NET" acima.
-    ServiceTier = "flex",
+    ServiceTier = ChatServiceTier.Flex,   // struct de valores nomeados, medido em OpenAI 2.13.0
 };
 
 ChatCompletion result = await chatClient.CompleteChatAsync(
@@ -94,7 +98,8 @@ string responseText = result.Content[0].Text;
 |---------|--------------------------|
 | Chat com usuário aguardando na tela | `default` (ou `auto`) |
 | Job async — relatório, enriquecimento, briefing | `flex` |
-| Job de alta prioridade com SLA apertado | `priority` (disponibilidade depende do plano OpenAI da conta) |
+| Job de alta prioridade com SLA apertado | `ChatServiceTier.Default` — **`priority` não existe** como valor tipado no SDK 2.13.0 (medido); um tier prioritário contratado com a OpenAI não tem membro correspondente aqui |
+| Carga previsível e alta, com capacidade reservada | `ChatServiceTier.Scale` |
 | Batch API (24 h) | Não se aplica — Batch tem custo próprio |
 
 > `auto` (padrão da API): OpenAI decide o tier baseado na carga. Use `flex` explícito
@@ -107,7 +112,8 @@ string responseText = result.Content[0].Text;
 | Anti-pattern | Problema |
 |-------------|----------|
 | Usar `flex` em completion interativa | Latência imprevisível — usuário percebe lentidão |
-| Usar `priority` (ou `default`) em batch noturno | Paga mais sem necessidade |
+| Usar `Default` em batch noturno | Paga mais sem necessidade |
+| Escrever `ServiceTier = "flex"` (string) | Não compila: o tipo é `ChatServiceTier` |
 | Espalhar `ServiceTier = "flex"` por vários handlers | Usar middleware de ChatOptions para centralizar |
 | Combinar flex tier com Batch API | São mecanismos distintos; não se somam |
 
@@ -116,7 +122,8 @@ string responseText = result.Content[0].Text;
 ## Checklist (verifiable by morph-eval)
 
 - [ ] Tier flex usado somente em jobs assíncronos (Worker Service / Hangfire), nunca em handlers de request HTTP síncrono
-- [ ] `ServiceTier` confirmado como string `"flex"` ou enum correto na versão do SDK instalada no projeto
+- [ ] `ServiceTier` usa o valor tipado (`ChatServiceTier.Flex` / `ResponseServiceTier.Flex`), nunca uma string
+- [ ] Nenhuma referência a um tier `priority` (não existe no SDK 2.13.0)
 - [ ] Jobs com flex tier não têm SLA de latência definido no contrato com o usuário final
 - [ ] Se o agente usa `IChatClient` abstrato, o `ServiceTier` foi validado que é passado corretamente
 
@@ -128,8 +135,9 @@ string responseText = result.Content[0].Text;
 - `ai-agents-batching` — alternativa de custo para volume alto de prompts independentes
 - `ai-agents-middleware-patterns` (Onda 2) — middleware para injetar `ChatOptions` globalmente
 - `ai-agents-providers-model-registry` — configuração provider-agnostic
-- OpenAI Service Tiers: https://platform.openai.com/docs/guides/service-tiers
+- OpenAI Service Tiers: https://platform.openai.com/docs/guides/service-tiers (lido 2026-09-08)
+- Superfície C# medida na assembly `OpenAI` 2.13.0 em 2026-09-08
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/service-tier-flex.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/service-tier-flex.md v2.0 (2026-09-08)*