senado-br-mcp 3.9.0 → 3.10.0

package/dist/call-shape.js

@@ -37,6 +37,13 @@
  */
 export function classifyError(message) {
     const m = message.toLowerCase();
+    // PRIMEIRO de todos, e de propósito: a rota que não existe na fonte é
+    // defeito NOSSO (montamos um caminho errado), e a palavra que a nomeia —
+    // "inexistente" — cairia em `nao_encontrado` logo abaixo, que é exatamente a
+    // conflação que o conserto de 24/09/2026 desfez na borda da rede. A frase
+    // vem de `MSG_ROTA_INEXISTENTE`; ela não é vocabulário da fonte, é nosso.
+    if (m.includes("defeito do servidor mcp"))
+        return "defeito";
     // A fronteira de palavra vai só no INÍCIO. Os padrões são RADICAIS
     // ("vazi", "obrigatóri", "indisponív") justamente porque a flexão muda o
     // fim: `\bvazi\b` não casa "vazia", e foi assim que "Resposta upstream
@@ -166,3 +173,43 @@ export function classifyThrown(error) {
     }
     return classifyError(error instanceof Error ? error.message : String(error));
 }
+/**
+ * Classe de um erro JSON-RPC do PROTOCOLO, pelo código antes da mensagem.
+ *
+ * POR QUE ELE CHEGA AQUI AGORA. Até 24/09/2026 este arquivo só era chamado de
+ * dentro do handler, com a exceção da tool na mão — e o cabeçalho acima ainda
+ * registra o limite daquele desenho: *erro de validação de esquema NÃO chega a
+ * esta camada; o SDK o responde antes do handler, e a chamada não é contada nem
+ * como chamada nem como erro*. Era verdade, e era o defeito: a recusa de esquema
+ * não gerava linha NENHUMA de telemetria. Medido na produção em 24/09/2026 pela
+ * rota do dono, ela sai como HTTP **200** com `result.isError: true` e sem
+ * código JSON-RPC; e ferramenta inexistente sai como **200** com o código
+ * **−32602** (não −32601, como se supunha). Desde então a telemetria lê o
+ * ENVELOPE da resposta (src/envelope.ts) e estes casos passam a existir.
+ *
+ * Os códigos reservados pela especificação JSON-RPC 2.0 dizem, sem ambiguidade
+ * de idioma, de quem é o conserto:
+ *
+ *  - −32700 parse error, −32600 invalid request, −32601 method not found e
+ *    −32602 invalid params são o CHAMADOR mandando algo que o protocolo
+ *    recusa. É `contrato` — e o painel exclui `contrato` da taxa de erro
+ *    (`eh_recusa_de_contrato()`), porque ferramenta que recusa chamada
+ *    malformada está funcionando;
+ *  - −32603 internal error é erro NOSSO, que escapou. É `defeito`, e por
+ *    decisão do dono em 24/09/2026 ele entra na fila de saúde do painel: sem
+ *    isso passaríamos a medir e continuaríamos a não agir.
+ *
+ * Código fora dessa faixa (erro definido pelo servidor, −32000 e abaixo) cai
+ * na mensagem, que é o caminho de `classifyError`.
+ *
+ * Cópia FIEL de sih-br-mcp/worker/src/call-shape.ts, onde a função estreou:
+ * classe medida por servidor com classificador diferente não é comparável, e
+ * comparar os sete é a razão de existir da seção de saúde do painel.
+ */
+export function classeDoErroRpc(code, message) {
+    if (code === -32700 || code === -32600 || code === -32601 || code === -32602)
+        return "contrato";
+    if (code === -32603)
+        return "defeito";
+    return classifyError(message);
+}

package/dist/envelope.js

@@ -0,0 +1,257 @@
+/**
+ * Leitura do ENVELOPE da resposta — o que transforma "o container devolveu
+ * HTTP 200" em "esta mensagem deu certo / esta falhou, e por quê".
+ *
+ * O PROBLEMA QUE ESTE ARQUIVO RESOLVE, E QUE AQUI É PIOR QUE NO `sih`. A
+ * telemetria deste Worker decide o desfecho pelo HTTP da resposta, e em cima
+ * disso `protocolNamesFromBody` (em src/instrument.ts) tinha a linha `if (status < 400) continue`, com
+ * o comentário "o hook de tools já gravou esta". A reconciliação era por STATUS,
+ * e supunha que 200 implica que o hook gravou. Quando a tool NÃO CHEGA A RODAR
+ * — recusa de esquema do zod, antes do handler — ninguém grava, e o `continue`
+ * fecha a única outra porta. O `sih` carimbava `ok` numa falha: número errado.
+ * Aqui não havia número NENHUM: a chamada não era contada nem como chamada.
+ *
+ * Medido na produção em 24/09/2026, pela rota do dono, no ilo, uis, senado e
+ * bcb — os quatro idênticos, e são DUAS formas, não uma: recusa de esquema sai
+ * HTTP 200 com `result.isError: true` e SEM código JSON-RPC; ferramenta
+ * inexistente sai HTTP 200 com o código −32602 (não −32601). Os dois são 200,
+ * então os dois caíam no `continue`.
+ *
+ * POR QUE NÃO BUFFERIZAR. Este Worker não é proxy — quem produz a resposta é o
+ * `createMcpHandler` aqui dentro —, mas a técnica é a mesma e pelo mesmo motivo:
+ * segurar bytes para ler o fim trocaria um defeito de medição por um defeito de
+ * produto (a lição do `sih`, cuja série de 34 anos leva ~30 s). O corpo é TEADO
+ * (`ReadableStream.tee()`): um ramo segue intocado para o cliente, no mesmo
+ * ritmo de antes, e o outro é lido aqui em `ctx.waitUntil`, depois que a
+ * resposta já saiu.
+ *
+ * O TEE RESOLVE, DE QUEBRA, UM PROBLEMA DE TEMPO. O hook de tools escreve
+ * durante a execução da tool, que num transporte SSE pode terminar DEPOIS de o
+ * handler já ter devolvido a Response. Ler o envelope até o fim do stream é,
+ * por construção, esperar a tool acabar — é só então que se sabe o que o hook
+ * gravou, e a reconciliação por nome (src/instrument.ts) só vale aí.
+ *
+ * REGRA DE OURO DESTE MÓDULO: ele nunca lança e nunca segura bytes. Qualquer
+ * coisa que ele não entenda vira "sem desfecho", e quem chama cai no critério
+ * antigo (o HTTP). Medir pior é aceitável; atrapalhar a resposta do usuário não é.
+ *
+ * DOIS TETOS, pelo mesmo motivo. Um evento SSE acumulado passa de
+ * `MAX_EVENTO_BYTES` → é descartado sem parsear (o `isError` pode estar no fim
+ * do JSON, mas mensagem de erro é curta: evento gigante é quase certamente
+ * resultado feliz, e o teto troca uma classificação improvável por um limite de
+ * memória e de CPU garantido). Mais de `MAX_DESFECHOS` respostas no mesmo corpo
+ * → o resto é ignorado; lote JSON-RPC de verdade tem punhado de mensagens.
+ *
+ * O CAMINHO DE ERRO-MOLE FICA DE FORA, de propósito. Ferramenta que responde
+ * ausência como DADO — uma resposta de SUCESSO cujo payload diz "não há" — está
+ * funcionando, e continua sendo `ok`. O que conta como falha é `isError: true`
+ * ou um erro JSON-RPC, nada mais. (No `sih`, de onde este arquivo vem, isso é a
+ * decisão 38 e seis ferramentas dependem dela; aqui o erro de tool já nasce de
+ * `IlostatUserError` / `IlostatUpstreamError` e vira `isError`.)
+ *
+ * Cópia de sih-br-mcp/worker/src/envelope.ts, porque o classificador não pode
+ * divergir entre os sete. O que muda é só este cabeçalho e o `teeResposta` do
+ * fim, que lá não existe: o `sih` monta a Response do zero a partir do upstream
+ * e teia no caminho; aqui a Response já vem pronta do handler.
+ */
+import { classeDoErroRpc, classifyError, errorText } from "./call-shape.js";
+/** Teto de bytes acumulados por evento SSE (ou por linha) antes de desistir dele. */
+export const MAX_EVENTO_BYTES = 64 * 1024;
+/** Teto de respostas rastreadas por corpo. */
+export const MAX_DESFECHOS = 64;
+/**
+ * Desfecho de uma resposta JSON-RPC, com o `id` que a liga ao pedido.
+ * `null` quando o objeto não é uma resposta identificável:
+ *  - sem `id` (ou `id: null`, que é a resposta a um pedido que nem parseou) —
+ *    não há a que ligar, e o chamador fica com o critério do HTTP;
+ *  - sem `result` e sem `error` — não é resposta (é notificação, ou lixo).
+ */
+export function desfechoDaResposta(msg) {
+    if (!msg || typeof msg !== "object" || Array.isArray(msg))
+        return null;
+    const m = msg;
+    if (typeof m.id !== "string" && typeof m.id !== "number")
+        return null;
+    const id = String(m.id);
+    if (m.error && typeof m.error === "object") {
+        const e = m.error;
+        const code = typeof e.code === "number" ? e.code : undefined;
+        const texto = typeof e.message === "string" ? e.message : "";
+        return { id, desfecho: { erro: true, classe: classeDoErroRpc(code, texto) } };
+    }
+    if (m.result && typeof m.result === "object") {
+        const r = m.result;
+        if (r.isError === true) {
+            return { id, desfecho: { erro: true, classe: classifyError(errorText(m.result)) } };
+        }
+        return { id, desfecho: { erro: false, classe: "" } };
+    }
+    // `result` primitivo (o SDK responde `{}` em alguns métodos, mas nunca um
+    // escalar) ainda é sucesso; o que não é resposta é o objeto sem os dois.
+    if (m.result !== undefined)
+        return { id, desfecho: { erro: false, classe: "" } };
+    return null;
+}
+/**
+ * O desfecho de UMA mensagem do pedido, já com o CRITÉRIO DE RESERVA aplicado.
+ *
+ * Regra: vale o que o envelope disse. Quando o envelope não disse nada — `id`
+ * ausente (notificação), stream cortado, evento grande demais, resposta que
+ * não parseou —, vale o HTTP do container, que era o critério único até
+ * 24/09/2026. Nunca se inventa classe: sem leitura, a classe é "".
+ */
+export function resolveDesfecho(id, desfechos, falhouHttp) {
+    const lido = id === "" ? undefined : desfechos.get(id);
+    return lido ?? { erro: falhouHttp, classe: "" };
+}
+/**
+ * Lê o corpo da resposta aos pedaços e vai colhendo desfechos por `id`.
+ *
+ * Aceita os dois formatos que o transporte Streamable HTTP usa: SSE (`data:`
+ * por evento, evento fechado por linha em branco, várias linhas `data:` do
+ * mesmo evento juntadas por `\n`) e JSON cru (resposta direta, sem stream).
+ * Linhas `event:`, `id:`, `retry:` e comentários (`:`) são ignoradas.
+ */
+export class LeitorDeEnvelope {
+    resto = "";
+    descartandoLinha = false;
+    evento = [];
+    bytesDoEvento = 0;
+    eventoEstourado = false;
+    viuSse = false;
+    cru = "";
+    /** Desfechos colhidos, por `id` de mensagem JSON-RPC. */
+    desfechos = new Map();
+    /** Entrega mais um pedaço de TEXTO já decodificado. Nunca lança. */
+    push(texto) {
+        if (!this.viuSse && this.cru.length < MAX_EVENTO_BYTES)
+            this.cru += texto;
+        this.resto += texto;
+        for (;;) {
+            const quebra = this.resto.indexOf("\n");
+            if (quebra < 0)
+                break;
+            const linha = this.resto.slice(0, quebra);
+            this.resto = this.resto.slice(quebra + 1);
+            if (this.descartandoLinha) {
+                // Fim da linha gigante que foi descartada: o evento inteiro cai junto,
+                // porque o JSON dele está incompleto.
+                this.descartandoLinha = false;
+                this.eventoEstourado = true;
+                continue;
+            }
+            this.linha(linha.endsWith("\r") ? linha.slice(0, -1) : linha);
+        }
+        // Linha sem fim à vista e já maior que o teto: para de acumular em vez de
+        // crescer com o corpo (uma resposta de 34 anos é uma única linha `data:`).
+        if (this.resto.length > MAX_EVENTO_BYTES) {
+            this.resto = "";
+            this.descartandoLinha = true;
+        }
+    }
+    /** Fecha o que ficou pendente. Chamar uma vez, ao fim do stream. */
+    end() {
+        if (this.resto !== "" && !this.descartandoLinha) {
+            const linha = this.resto.endsWith("\r") ? this.resto.slice(0, -1) : this.resto;
+            this.resto = "";
+            this.linha(linha);
+        }
+        this.fechaEvento();
+        // Corpo que nunca teve uma linha `data:` é JSON cru.
+        if (!this.viuSse)
+            this.registra(this.cru);
+    }
+    linha(linha) {
+        if (linha === "") {
+            this.fechaEvento();
+            return;
+        }
+        if (!linha.startsWith("data:"))
+            return;
+        this.viuSse = true;
+        const pedaco = linha.slice(5).replace(/^ /, "");
+        this.bytesDoEvento += pedaco.length;
+        if (this.bytesDoEvento > MAX_EVENTO_BYTES) {
+            this.eventoEstourado = true;
+            this.evento = [];
+            return;
+        }
+        this.evento.push(pedaco);
+    }
+    fechaEvento() {
+        const partes = this.evento;
+        const estourou = this.eventoEstourado;
+        this.evento = [];
+        this.bytesDoEvento = 0;
+        this.eventoEstourado = false;
+        if (estourou || partes.length === 0)
+            return;
+        this.registra(partes.join("\n"));
+    }
+    registra(json) {
+        if (json === "" || this.desfechos.size >= MAX_DESFECHOS)
+            return;
+        let obj;
+        try {
+            obj = JSON.parse(json);
+        }
+        catch {
+            return; // pedaço cortado ao meio, ou não era JSON: fica sem desfecho
+        }
+        for (const item of Array.isArray(obj) ? obj : [obj]) {
+            if (this.desfechos.size >= MAX_DESFECHOS)
+                return;
+            const d = desfechoDaResposta(item);
+            if (d)
+                this.desfechos.set(d.id, d.desfecho);
+        }
+    }
+}
+/**
+ * Consome um stream inteiro e devolve os desfechos por `id`. Nunca lança: se o
+ * stream for cortado no meio (cliente desconectou, container caiu), vale o que
+ * deu para ler até ali e o resto fica sem desfecho.
+ */
+export async function desfechosDoCorpo(corpo) {
+    const leitor = new LeitorDeEnvelope();
+    const decoder = new TextDecoder();
+    const reader = corpo.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value)
+                leitor.push(decoder.decode(value, { stream: true }));
+        }
+        leitor.push(decoder.decode());
+    }
+    catch {
+        // Stream interrompido: o que já foi lido continua valendo.
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // ignorado
+        }
+    }
+    leitor.end();
+    return leitor.desfechos;
+}
+/**
+ * Parte o corpo da resposta em dois: o que vai para o cliente e o que a
+ * telemetria lê. Só isto, e nunca mais que isto — a Response devolvida tem o
+ * mesmo status, o mesmo statusText e os mesmos cabeçalhos da original.
+ *
+ * Resposta sem corpo (204, HEAD, erro montado na borda) devolve `corpo: null` e
+ * a própria Response intacta: não há o que teiar, e `new Response(null, resp)`
+ * seria uma cópia à toa.
+ */
+export function teeResposta(resposta) {
+    if (!resposta.body)
+        return { paraCliente: resposta, paraLeitura: null };
+    const [cliente, leitura] = resposta.body.tee();
+    return { paraCliente: new Response(cliente, resposta), paraLeitura: leitura };
+}

package/dist/instrument.js

@@ -28,6 +28,7 @@
  * connector is only identifiable via the secret header his MCP clients send
  * (SELF_HEADER, value = the SELF_MARKER Wrangler secret).
  */
+import { resolveDesfecho } from "./envelope.js";
 import { classifyError, classifyThrown, errorText, paramNames } from "./call-shape.js";
 import { incr, incrTool } from "./metrics.js";
 import { callCache, cacheClass } from "./observability/call-context.js";
@@ -62,7 +63,7 @@ export function tagRequest(request, selfSecret, sessao = "") {
         sessao,
     };
 }
-export function instrumentTool(name, cb, analytics, tag) {
+export function instrumentTool(name, cb, analytics, tag, gravados) {
     return async (...args) => {
         incr("toolCalls");
         let isError = false;
@@ -93,6 +94,12 @@ export function instrumentTool(name, cb, analytics, tag) {
             // chamada nem como erro. Medido em 10/09/2026 pelo /metrics: três
             // chamadas com argumento de forma errada não moveram o contador.
             recordToolCall(name, isError, stats, analytics, tag, classe, paramNames(args));
+            // Recibo desta requisicao: e contra ele que recordProtocolMethods
+            // reconcilia. Fica no `finally` junto da gravacao, para os dois nunca
+            // discordarem. A recusa de esquema NAO passa por aqui -- e exatamente
+            // por isso que ela nao deixa recibo, e a linha dela e escrita la.
+            if (gravados)
+                gravados.set(name, (gravados.get(name) ?? 0) + 1);
         }
     };
 }
@@ -135,71 +142,52 @@ function recordToolCall(name, isError, stats, analytics, tag, errorClass = "", p
     }
 }
 /**
- * Métodos de PROTOCOLO, gravados na camada HTTP.
+ * As mensagens do corpo que ainda precisam de linha, já descontado o recibo.
  *
- * `instrumentTool` só vê `tools/call`: ela envolve o callback da tool.
- * `initialize`, `tools/list`, `notifications/*`, `ping` e o que mais o
- * cliente mande (`server/discover`, por exemplo) atravessam o transporte sem
- * tocar tool nenhuma — e são eles que contam o FUNIL DE SESSÃO: quantos
- * `initialize` viram chamada de ferramenta de verdade, que é o que separa
- * "acharam o servidor" de "usaram o servidor". Medido em 2026-09-10: só o
- * sih-br-mcp os gravava, porque lá o Worker é um proxy que lê o corpo
- * JSON-RPC antes de encaminhar. Aqui o servidor roda dentro do Worker, e o
- * corpo vem de uma CÓPIA tirada antes de o handler consumir o stream
- * (src/index.ts). Desde 2026-09-16 a frota inteira grava igual.
- *
- * Mesmo esquema de blobs, com o método no lugar do nome da tool — igual ao
- * sih. O painel separa os dois pelo nome (`metodo_de_protocolo`). Classe de
- * cache, classe de erro e parâmetros ficam vazios; fetches e hits, zero.
- *
- * O que entra, e de onde vem o desfecho:
- *  - todo método que não é `tools/call` → uma linha, "ok" se o HTTP da
- *    resposta for < 400, "error" senão. LIMITAÇÃO, a mesma do sih: erro
- *    JSON-RPC que viaja dentro de um 200 (método desconhecido, -32601) sai
- *    como "ok" — ler exigiria consumir o corpo que está sendo devolvido;
- *  - `tools/call` só quando o HTTP é ≥ 400: o transporte recusou antes de
- *    despachar (Accept errado, sessão inválida, Origin estrangeiro) e a tool
- *    nunca rodou; sem isto a recusa seria invisível. Com HTTP < 400 a
- *    `instrumentTool` já gravou a linha, com o desfecho de verdade — não se
- *    grava de novo;
- *  - lote JSON-RPC (array) → uma linha por item; item sem `method` (resposta
- *    do cliente, corpo que não é JSON) → nada.
- *
- * Só no Analytics Engine: os contadores do /metrics continuam contando tools.
+ * `gravados` é CONSUMIDO (decrementado) durante a varredura. Chamar sem ele
+ * significa "a instrumentTool não gravou nada".
  */
-export function protocolNamesFromBody(body, status) {
+export function protocolMessagesFromBody(body, gravados) {
     const itens = Array.isArray(body) ? body : [body];
-    const nomes = [];
+    const mensagens = [];
     for (const item of itens) {
         if (!item || typeof item !== "object")
             continue;
         const msg = item;
         if (typeof msg.method !== "string" || msg.method === "")
             continue;
+        const id = typeof msg.id === "string" || typeof msg.id === "number" ? String(msg.id) : "";
         if (msg.method === "tools/call") {
-            if (status < 400)
-                continue; // instrumentTool já gravou esta
             const params = msg.params;
-            nomes.push(typeof params?.name === "string" && params.name !== "" ? params.name : "tools/call");
+            const nome = typeof params?.name === "string" && params.name !== "" ? params.name : "tools/call";
+            const recibo = gravados?.get(nome) ?? 0;
+            if (recibo > 0) {
+                gravados?.set(nome, recibo - 1); // a instrumentTool já gravou esta
+                continue;
+            }
+            mensagens.push({ nome, id });
         }
         else {
-            nomes.push(msg.method);
+            mensagens.push({ nome: msg.method, id });
         }
     }
-    return nomes;
+    return mensagens;
 }
 /**
  * Grava no Analytics Engine os métodos de protocolo de um POST no endpoint
- * MCP (ver protocolNamesFromBody). Devolve os nomes gravados. Sem binding,
- * não grava nada.
+ * MCP (ver acima). Devolve os nomes gravados. Sem binding, não grava nada.
+ *
+ * `desfechos` é o que a leitura do envelope colheu por `id`; sem ele — corpo
+ * não teado, stream cortado — vale o HTTP, que é o critério de reserva.
  */
-export function recordProtocolMethods(analytics, tag, body, status) {
+export function recordProtocolMethods(analytics, tag, body, status, desfechos = new Map(), gravados) {
     if (!analytics || body === undefined)
         return [];
     const cliente = clientNameFromBody(body);
-    const nomes = protocolNamesFromBody(body, status);
-    const isError = status >= 400;
-    for (const name of nomes) {
+    const mensagens = protocolMessagesFromBody(body, gravados);
+    const falhouHttp = status >= 400;
+    for (const { nome: name, id } of mensagens) {
+        const { erro: isError, classe } = resolveDesfecho(id, desfechos, falhouHttp);
         try {
             analytics.writeDataPoint({
                 indexes: [name],
@@ -210,7 +198,7 @@ export function recordProtocolMethods(analytics, tag, body, status) {
                     tag?.self ? "self" : "",
                     tag?.country ?? "",
                     tag?.asOrg ?? "",
-                    "",
+                    classe,
                     "",
                     tag?.sessao ?? "",
                     name === "initialize" ? cliente : "",
@@ -222,7 +210,7 @@ export function recordProtocolMethods(analytics, tag, body, status) {
             // Falha de telemetria nunca quebra nem atrasa a resposta.
         }
     }
-    return nomes;
+    return mensagens.map((m) => m.nome);
 }
 /**
  * SESSÃO E CLIENTE (blobs 9 e 10, desde 2026-09-17).

package/dist/server.js

@@ -112,7 +112,7 @@ export function createServer(env, ctx, options = {}) {
                 openWorldHint: true,
             },
             _meta: toolMetaForProfile(toolProfile),
-        }, instrumentTool(name, profiledCallback, analytics, options.requestTag));
+        }, instrumentTool(name, profiledCallback, analytics, options.requestTag, options.gravados));
     };
     const baseUrl = env.SENADO_BASE_URL || "https://legis.senado.leg.br/dadosabertos";
     const admBaseUrl = env.SENADO_ADM_BASE_URL || "https://adm.senado.gov.br/adm-dadosabertos";

package/dist/throttle/adm.js

@@ -4,7 +4,7 @@
  *
  * Differences from the legislative API:
  * - no `.json` suffix on paths
- * - some collections 404 instead of returning an empty array
+ * - a chave fora da cobertura responde 404, não array vazio
  * - some datasets are very large (CEAPS year ≈ 10 MB), hence the raised guard
  *
  * Reuses upstreamFetch, so the global token bucket, concurrency limit,
@@ -16,7 +16,15 @@ export async function admFetch(path, params = {}, baseUrl, options = {}) {
     const base = baseUrl || SENADO_ADM_BASE_URL_DEFAULT;
     return upstreamFetch(`/api/v1${path}`, params, base, {
         noJsonSuffix: true,
-        treat404AsEmpty: true,
+        // `absent`, e não o `treat404AsEmpty: true` que estava aqui até 24/09/2026.
+        // A flag antiga transformava TODO 404 em `[]`, e com isso 16 pontos de
+        // chamada — CEAPS, supridos, remunerações, horas extras, contratos — diziam
+        // "count: 0" para ano que a fonte NÃO PUBLICA. Medido: `/supridos/2005` e
+        // `/senadores/despesas_ceaps/2007` respondem 404, enquanto a chave válida
+        // sem dado responde `200 []`. Logo o 404 aqui nunca significou "vazio".
+        // Quem precisa do `[]` pede `on404: "empty"` explicitamente, pelo
+        // `options` abaixo, e assume o ônus de desfazer a ambiguidade.
+        on404: "absent",
         ...options,
     });
 }

package/dist/throttle/upstream.js

@@ -42,6 +42,49 @@ export class UpstreamError extends Error {
         this.name = "UpstreamError";
     }
 }
+/**
+ * Frase-chave da mensagem de rota inexistente. Vive numa constante porque
+ * `classifyError` casa contra ela para devolver `defeito`: se o texto mudar
+ * num lugar só, a telemetria volta a mentir em silêncio.
+ */
+export const MSG_ROTA_INEXISTENTE = "Rota inexistente na fonte (defeito do servidor MCP)";
+/**
+ * A fonte respondeu, e respondeu que a CHAVE pedida não existe no acervo.
+ *
+ * Separada de `UpstreamError` porque não é falha da fonte: é resposta dela.
+ * A mensagem é escrita para cair em `nao_encontrado` no `classifyError`.
+ */
+export class RecursoAusenteError extends UpstreamError {
+    constructor(path) {
+        super(`[${path}] A fonte não tem registro para esta chave: o recurso não existe no acervo publicado.`, 404, false);
+        this.name = "RecursoAusenteError";
+    }
+}
+/**
+ * Distingue os DOIS 404 que as APIs do Senado emitem — medido em 24/09/2026
+ * nas duas bases, legislativa e administrativa:
+ *
+ * | caso                          | corpo                                                |
+ * |-------------------------------|------------------------------------------------------|
+ * | rota não existe (erro NOSSO)  | problem+json com `detail: "No static resource ..."`  |
+ * | chave sem registro            | corpo vazio, ou problem+json SEM `detail`            |
+ *
+ * `/servidores/xxxx` traz o `detail`; `/supridos/2005` vem com
+ * `Content-Length: 0`; `/taquigrafia/notas/sessao/99999999` traz
+ * `{instance,status,title}` sem `detail`. Só o primeiro é defeito nosso.
+ */
+export function rotaInexistente(corpo) {
+    if (!corpo.trim())
+        return false;
+    let detail;
+    try {
+        detail = JSON.parse(corpo).detail;
+    }
+    catch {
+        return false;
+    }
+    return typeof detail === "string" && /^No static resource\b/i.test(detail.trim());
+}
 /**
  * Parse an HTTP Retry-After header (RFC 9110 §10.2.3) into milliseconds to wait.
  * Accepts the delta-seconds form ("5") and the HTTP-date form; returns null when
@@ -138,10 +181,16 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
                 }
                 break;
             }
-            if (response.status === 404 && options.treat404AsEmpty) {
+            if (response.status === 404 && options.on404) {
                 incr("upstreamCalls");
                 log("upstream", path, 404, Date.now() - startTime, attempt);
-                return [];
+                const corpo404 = await response.text();
+                if (rotaInexistente(corpo404)) {
+                    throw new UpstreamError(`[${path}] ${MSG_ROTA_INEXISTENTE} — o caminho montado não existe na API do Senado.`, 404, false);
+                }
+                if (options.on404 === "empty")
+                    return [];
+                throw new RecursoAusenteError(path);
             }
             if (!response.ok) {
                 throw new UpstreamError(`[${path}] Upstream retornou HTTP ${response.status}`, response.status, response.status >= 500);

package/dist/tools/contratacoes.js

@@ -86,6 +86,56 @@ export function ordenarEPaginar(lista, ordem, offset, limite) {
     const ordenada = ordem === "desc" ? [...lista].reverse() : lista;
     return ordenada.slice(offset, offset + limite);
 }
+/**
+ * A lista-pai crua contém o `id`?
+ *
+ * Separada de `paiExiste` para ser testável pela convenção da casa (unitário,
+ * sem rede): a decisão que importa é a COMPARAÇÃO, não o fetch.
+ *
+ * Compara como NÚMERO dos dois lados — o id vem `number` do esquema da tool e a
+ * fonte já o serviu como string em outras coleções —, e ausência (`null`,
+ * `undefined`, `""`) nunca vira 0: `Number("")` é 0, e sem a guarda um registro
+ * sem id casaria com `id: 0` ([[notacao-do-codigo-limpa-dos-dois-lados]]).
+ */
+export function contemId(lista, id) {
+    return ensureArray(lista).some((c) => {
+        const bruto = c?.id;
+        if (bruto === null || bruto === undefined || bruto === "")
+            return false;
+        return Number(bruto) === id;
+    });
+}
+/**
+ * A contratação `id` existe na lista-pai de `tipo`?
+ *
+ * POR QUE ISTO EXISTE. A API administrativa responde **404 com corpo vazio**
+ * tanto para sub-recurso de pai INEXISTENTE quanto para seção legitimamente
+ * VAZIA — medido em 24/09/2026: `/contratos/99999999/itens` e
+ * `/contratos/541/itens` (pai real, seção sem registro) dão o mesmo 404, e
+ * `/contratos/632/itens` dá 200. A fonte não distingue os dois, então a borda
+ * da rede também não pode: é a única rota adm que fica em `on404: "empty"`, e
+ * o preço disso é desfazer a ambiguidade AQUI.
+ *
+ * Custo: nenhum, na prática. Confirmar o pai é procurar o id na lista completa
+ * que `senado_contratos` / `senado_contratacoes_lista` já baixam e cacheiam —
+ * a chamada usa as MESMAS chaves de cache, então é acerto de cache. Não há
+ * rota de item único: conferido no Swagger, `/contratos/632` dá 404 e `?id=632`
+ * é ignorado (devolve a base inteira).
+ *
+ * Em falha de rede devolve `null` (indeterminado), não `false`: a fonte fora do
+ * ar não é prova de que o contrato não existe.
+ */
+export async function paiExiste(tipo, id, admBaseUrl) {
+    try {
+        const { value } = tipo === "contratos"
+            ? await cachedFetchWithMeta("senado_contratos", {}, CACHE_SEMI_STATIC, () => admFetchLarge("/contratacoes/contratos", {}, admBaseUrl))
+            : await cachedFetchWithMeta("senado_contratacoes_lista", { tipo }, CACHE_SEMI_STATIC, () => admFetch(`/contratacoes/${tipo}`, {}, admBaseUrl));
+        return contemId(value, id);
+    }
+    catch {
+        return null;
+    }
+}
 export function registerContratacoesTools(server, admBaseUrl) {
     // Q1. senado_contratos
     server.tool("senado_contratos", "Busca contratos administrativos do Senado por fornecedor, CNPJ, ano, número, objeto ou mão de obra (base completa baixada e filtrada no Worker; busca parcial sem acento em objeto/fornecedor/número). Retorna `{ count, total, contratos }`, onde cada item traz `id`, `numero`, `objeto`, `empresa {nome, cnpj}`, `subEspecie`, `dataAssinatura`, `vigencia` e `unidadeGestora`. Atenção: a fonte NÃO publica o valor do contrato (nenhum campo monetário aqui nem nas seções de detalhe; apenas a seção `aditivos` de `senado_contratacao_detalhe` traz `valor`, referente ao termo aditivo) — não gaste chamadas procurando valor. A lista mistura subespécies (CT = contratos, AC = acordos de cooperação, TD = termos de doação etc.); distinga pelo campo `subEspecie` retornado. Limitado a `limite` itens (padrão 50, máx 500), com `aviso` quando há truncamento. Use o `id` retornado em `senado_contratacao_detalhe` para itens, pagamentos, garantias ou aditivos.", {
@@ -144,7 +194,7 @@ export function registerContratacoesTools(server, admBaseUrl) {
         }
     });
     // Q2. senado_contratacao_detalhe
-    server.tool("senado_contratacao_detalhe", "Detalha uma seção específica de uma contratação já identificada pelo `id`. `tipo` indica a natureza do registro: `contratos` (contrato firmado; padrão), `atas_registro_preco` (compromisso de preços para compras futuras) ou `notas_empenho` (reserva orçamentária do gasto). `secao` escolhe o aspecto: `itens`, `pagamentos`, `garantias` (qualquer `tipo`), `aditivos` (só `contratos`) ou `acionamentos` (só `atas_registro_preco`). Retorna `{ id, tipo, secao, count, total, itens }` com os registros brutos da seção (campos conforme a API administrativa), limitados a `limite` (padrão 100, máx 500) — `count < total` indica truncagem; seção sem registros retorna `count` 0 e `itens` vazio; combinações `secao`×`tipo` inválidas (ex.: `aditivos` fora de contratos) retornam erro. Atenção: a fonte NÃO publica o valor do contrato em nenhuma seção; apenas `aditivos` traz `valor`, referente ao termo aditivo (às vezes nulo) — não procure valor monetário em itens/pagamentos/garantias. Obtenha o `id` via `senado_contratos` ou `senado_contratacoes_lista` — para localizar a contratação (não detalhá-la) use aquelas ferramentas.", {
+    server.tool("senado_contratacao_detalhe", "Detalha uma seção específica de uma contratação já identificada pelo `id`. `tipo` indica a natureza do registro: `contratos` (contrato firmado; padrão), `atas_registro_preco` (compromisso de preços para compras futuras) ou `notas_empenho` (reserva orçamentária do gasto). `secao` escolhe o aspecto: `itens`, `pagamentos`, `garantias` (qualquer `tipo`), `aditivos` (só `contratos`) ou `acionamentos` (só `atas_registro_preco`). Retorna `{ id, tipo, secao, count, total, itens }` com os registros brutos da seção (campos conforme a API administrativa), limitados a `limite` (padrão 100, máx 500) — `count < total` indica truncagem; seção sem registros retorna `count` 0 e `itens` vazio (o `id` é conferido na lista-pai antes, então `count` 0 significa mesmo seção vazia, não contratação inexistente); `id` que não existe e combinações `secao`×`tipo` inválidas (ex.: `aditivos` fora de contratos) retornam erro. Atenção: a fonte NÃO publica o valor do contrato em nenhuma seção; apenas `aditivos` traz `valor`, referente ao termo aditivo (às vezes nulo) — não procure valor monetário em itens/pagamentos/garantias. Obtenha o `id` via `senado_contratos` ou `senado_contratacoes_lista` — para localizar a contratação (não detalhá-la) use aquelas ferramentas.", {
         id: z.number().int().positive().describe("ID da contratação (campo 'id' das listas de contratos/atas/empenhos)"),
         tipo: z.enum(["contratos", "atas_registro_preco", "notas_empenho"]).optional().default("contratos").describe("contratos = contrato firmado (padrão); atas_registro_preco = compromisso de preços p/ compras futuras; notas_empenho = reserva orçamentária do gasto"),
         secao: z.enum(["itens", "pagamentos", "garantias", "aditivos", "acionamentos"]).describe("Aspecto a detalhar: itens/pagamentos/garantias (qualquer tipo); aditivos (só contratos); acionamentos (só atas_registro_preco)"),
@@ -166,8 +216,22 @@ export function registerContratacoesTools(server, admBaseUrl) {
             else {
                 path = `/contratacoes/${tipo}/${params.id}/${params.secao}`;
             }
-            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_contratacao_detalhe", { tipo, id: params.id, secao: params.secao }, CACHE_ON_DEMAND, () => admFetch(path, {}, admBaseUrl));
+            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_contratacao_detalhe", { tipo, id: params.id, secao: params.secao }, CACHE_ON_DEMAND, 
+            // `empty` sobrescreve o `absent` que `admFetch` passou a usar em
+            // 24/09/2026: aqui o 404 é mesmo ambíguo (ver `paiExiste`), e quem
+            // desfaz a ambiguidade é a conferência do pai, logo abaixo.
+            () => admFetch(path, {}, admBaseUrl, { on404: "empty" }));
             const todos = ensureArray(response);
+            // Seção vazia: só agora vale pagar a conferência do pai — e ela é
+            // acerto de cache. Pai ausente => ausência tipada (`nao_encontrado`);
+            // pai presente => o zero é VERDADE e segue como `count: 0`.
+            if (todos.length === 0) {
+                const existe = await paiExiste(tipo, params.id, admBaseUrl);
+                if (existe === false) {
+                    return toolError(`Não existe ${tipo} com id ${params.id}. Obtenha o id em ` +
+                        (tipo === "contratos" ? "senado_contratos" : "senado_contratacoes_lista") + ".");
+                }
+            }
             const limite = params.limite ?? 100;
             const prov = provenanceFor("SENADO_ADM", admBaseUrl, `/api/v1${path}`, {
                 dataset_id: `${tipo}=${params.id}; secao=${params.secao}`, retrieved_at: fetchedAt,

package/dist/tools/plenario.js

@@ -112,7 +112,14 @@ export function parseSessaoResultado(s) {
 /** Parse an orientacaoBancada votacao item (flat camelCase). */
 export function parseOrientacaoVotacao(v) {
     return {
-        codigoVotacao: v.codigoVotacaoSve ?? null,
+        // `codigoVotacaoSve`, com o nome da FONTE, e não `codigoVotacao`. Medido em
+        // 24/09/2026: é um TERCEIRO espaço de numeração — as 3 votações de
+        // 12/08/2026 são 13059/13159/13161 aqui, 7101/7102/7103 em
+        // `senado_votacoes_senador` e a sessão 581816 em `senado_obter_votacao`. O
+        // campo `codigoVotacaoSve` não aparece UMA vez em `/votacao`, então nenhuma
+        // tool o resolve; chamá-lo de `codigoVotacao` convidava a alimentar o
+        // `senado_obter_votacao` com ele e receber `count: 0` calado.
+        codigoVotacaoSve: v.codigoVotacaoSve ?? null,
         descricao: v.descricaoVotacao || null,
         materia: v.descricaoMateria ||
             (v.siglaTipoMateria ? `${v.siglaTipoMateria} ${v.numeroMateria}/${v.anoMateria}` : null),
@@ -214,7 +221,7 @@ export function registerPlenarioTools(server, baseUrl) {
         }
     });
     // F3. senado_orientacao_bancada
-    server.tool("senado_orientacao_bancada", "Orientação de bancada nas votações de plenário: como cada liderança partidária orientou o voto, com placar — essencial para análise de disciplina partidária. Retorna `{ count, votacoes }`, com cada votação trazendo `codigoVotacao`, `descricao`, `materia`, `dataInicio`, `dataTermino`, `sessao`, totais (`totalSim`, `totalNao`, `totalAbstencao`, `obstrucoes`), `quorumInicial`/`quorumFinal` e `orientacoes` (`partido`, `voto`). Informe `data` (um dia) ou o período `dataInicio`/`dataFim`. Para o resultado das sessões use `senado_resultado_plenario`.", {
+    server.tool("senado_orientacao_bancada", "Orientação de bancada nas votações de plenário: como cada liderança partidária orientou o voto, com placar — essencial para análise de disciplina partidária. Retorna `{ count, votacoes }`, com cada votação trazendo `codigoVotacaoSve`, `descricao`, `materia`, `dataInicio`, `dataTermino`, `sessao`, totais (`totalSim`, `totalNao`, `totalAbstencao`, `obstrucoes`), `quorumInicial`/`quorumFinal` e `orientacoes` (`partido`, `voto`). Informe `data` (um dia) ou o período `dataInicio`/`dataFim`. O `codigoVotacaoSve` é o identificador interno do sistema de votação eletrônica e pertence a um espaço de numeração próprio: NÃO serve como entrada de `senado_obter_votacao` (use a `data` com `senado_search_votacoes` para chegar ao código da votação). Para o resultado das sessões use `senado_resultado_plenario`.", {
         data: z.string().regex(/^\d{8}$/).optional().describe("Data da sessão (YYYYMMDD)"),
         dataInicio: z.string().regex(/^\d{8}$/).optional().describe("Data início do período (YYYYMMDD)"),
         dataFim: z.string().regex(/^\d{8}$/).optional().describe("Data fim do período (YYYYMMDD)"),

package/dist/tools/senadores.js

@@ -115,6 +115,14 @@ export function parseSenadorDetalhe(dados) {
 export function parseVotoSenador(v, codigoSenador) {
     const voto = ensureArray(v.votos).find((vt) => vt.codigoParlamentar === codigoSenador);
     return {
+        // O PAR, não um dos dois. Até 24/09/2026 este campo servia só o
+        // `codigoSessaoVotacao` (4 dígitos) e a descrição mandava usar
+        // `senado_obter_votacao` com ele — que filtrava por `codigoSessao` e
+        // respondia `count: 0`. Medido: 48 de 48 votos de um senador em 2026 saíam
+        // com código de 4 dígitos, ou seja, o caminho documentado quebrava sempre.
+        // Hoje as duas pontas resolvem, e emitir os dois poupa a varredura da
+        // janela: com `codigoSessao` o `obter_votacao` acerta de primeira.
+        codigoSessao: v.codigoSessao || null,
         codigoVotacao: v.codigoSessaoVotacao || v.codigoSessao || 0,
         data: v.dataSessao ? String(v.dataSessao).split("T")[0] : "",
         materia: v.identificacao || (v.sigla ? `${v.sigla} ${v.numero}/${v.ano}` : ""),
@@ -291,7 +299,7 @@ export function registerSenadoresTools(server, baseUrl) {
         }
     });
     // A4. senado_votacoes_senador (migrated to v3 /votacao?codigoParlamentar — legacy endpoint deprecated)
-    server.tool("senado_votacoes_senador", "Lista as votações nominais de um senador, mostrando como votou em cada matéria. Retorna `{ periodo, count, votos }`, cada voto com `codigoVotacao`, `data`, `materia`, `descricao`, `voto` e `resultado`, ordenados da mais recente para a mais antiga. Sem período usa o ano corrente; informe `ano` ou o par `dataInicio`/`dataFim` (YYYYMMDD). Requer `codigoSenador` (obtenha via `senado_listar_senadores`); para detalhes de uma votação específica use `senado_obter_votacao`.", {
+    server.tool("senado_votacoes_senador", "Lista as votações nominais de um senador, mostrando como votou em cada matéria. Retorna `{ periodo, count, votos }`, cada voto com `codigoSessao`, `codigoVotacao`, `data`, `materia`, `descricao`, `voto` e `resultado`, ordenados da mais recente para a mais antiga. Sem período usa o ano corrente; informe `ano` ou o par `dataInicio`/`dataFim` (YYYYMMDD). Requer `codigoSenador` (obtenha via `senado_listar_senadores`); para detalhes de uma votação específica (votos de todos os senadores) use `senado_obter_votacao` — os dois códigos são aceitos, e `codigoSessao` resolve direto.", {
         codigoSenador: z.number().int().positive().describe("Código único do senador"),
         ano: z.number().int().min(1900).max(2100).optional().describe("Ano das votações"),
         dataInicio: z.string().regex(/^\d{8}$/).optional().describe("Data início (YYYYMMDD)"),

package/dist/tools/supridos.js

@@ -191,8 +191,13 @@ export async function nomesSupridos(ano, admBaseUrl) {
 }
 export function registerSupridosTools(server, admBaseUrl) {
     // R1. senado_suprimento_fundos
-    server.tool("senado_suprimento_fundos", "Suprimento de fundos do Senado (adiantamentos a supridos): relação anual de supridos, atos de concessão, empenhos, movimentações ou transações de cartão corporativo, conforme `tipo`. Retorna `{ ano, tipo, count, total, registros }` (snake_case da API administrativa), filtrável por `filtro` textual e limitado por `limite` (padrão 100, máx 500); ao truncar, inclui `aviso`. Para maior/menor/média/mediana/distribuição/ranking ('quem mais recebeu', 'fornecedor com maior gasto', 'valor mediano') use `estatisticas=true` (só nos tipos `transacoes`, `empenhos`, `atos-concessao` — os demais não têm coluna de valor): SEM `agruparPor` = distribuição das linhas (min/máx/média/mediana/percentis) + top/bottom; COM `agruparPor` = grupos ranqueados por soma decrescente (grupos[0]=maior). A coluna de valor analisada é escolhida automaticamente conforme o `tipo`; o resultado já traz o rótulo legível dela em `campoAnalisado`. Registros sem valor são excluídos das estatísticas. Em atos de concessão, cada beneficiário é identificado pelo NOME (cruzado com o cadastro de supridos) e pode-se usar `agruparPor='suprido'` para ranquear por beneficiário. Informe o `ano` (>=2010); use os mesmos códigos administrativos vistos em `senado_contratacoes_lista` ou `senado_execucao_orcamentaria` para cruzar gastos.", {
-        ano: z.number().int().min(2010).max(2100).describe("Ano de referência"),
+    server.tool("senado_suprimento_fundos", "Suprimento de fundos do Senado (adiantamentos a supridos): relação anual de supridos, atos de concessão, empenhos, movimentações ou transações de cartão corporativo, conforme `tipo`. Retorna `{ ano, tipo, count, total, registros }` (snake_case da API administrativa), filtrável por `filtro` textual e limitado por `limite` (padrão 100, máx 500); ao truncar, inclui `aviso`. Para maior/menor/média/mediana/distribuição/ranking ('quem mais recebeu', 'fornecedor com maior gasto', 'valor mediano') use `estatisticas=true` (só nos tipos `transacoes`, `empenhos`, `atos-concessao` — os demais não têm coluna de valor): SEM `agruparPor` = distribuição das linhas (min/máx/média/mediana/percentis) + top/bottom; COM `agruparPor` = grupos ranqueados por soma decrescente (grupos[0]=maior). A coluna de valor analisada é escolhida automaticamente conforme o `tipo`; o resultado já traz o rótulo legível dela em `campoAnalisado`. Registros sem valor são excluídos das estatísticas. Em atos de concessão, cada beneficiário é identificado pelo NOME (cruzado com o cadastro de supridos) e pode-se usar `agruparPor='suprido'` para ranquear por beneficiário. Informe o `ano` (a fonte publica de 2013 em diante); use os mesmos códigos administrativos vistos em `senado_contratacoes_lista` ou `senado_execucao_orcamentaria` para cruzar gastos.", {
+        // 2013, e não o 2010 que estava aqui: medido em 24/09/2026, `/supridos/`
+        // de 2009 a 2012 responde 404 e 2013 responde 200. Com o
+        // `treat404AsEmpty` antigo, pedir 2011 devolvia `count: 0` — lia-se
+        // "o Senado não adiantou nada em 2011". O limite fecha a porta antes da
+        // rede (classe `contrato`); fora dela, a ausência agora é tipada.
+        ano: z.number().int().min(2013).max(2100).describe("Ano de referência (a fonte publica de 2013 em diante)"),
         tipo: z.enum(["supridos", "atos-concessao", "empenhos", "movimentacoes", "transacoes"]).optional().default("supridos").describe("Qual relação consultar (padrão: supridos)"),
         filtro: z.string().optional().describe("Filtro textual (nome, unidade...)"),
         estatisticas: z.boolean().optional().default(false).describe("Distribuição/ranking sobre as linhas: min/máx/média/mediana/percentis + top/bottom, ou grupos ranqueados por soma via agruparPor. Só para tipo transacoes/empenhos/atos-concessao"),

package/dist/tools/taquigrafia.js

@@ -85,7 +85,15 @@ export function registerTaquigrafiaTools(server, baseUrl) {
             // The acervo answers 404 for codes without transcript (CN joint sessions,
             // cancelled/not-held sessions, some solemn ones) — serve the promised
             // empty result instead of an upstream error.
-            () => upstreamFetch(path, {}, baseUrl, { treat404AsEmpty: true }));
+            //
+            // `empty` DE PROPÓSITO, ao contrário da classe administrativa que a
+            // varredura de 24/09/2026 converteu para `absent`: aqui o zero não é
+            // calado. Ele vem com `NOTAS_TAQUIGRAFICAS_AVISO_VAZIO`, que nomeia os
+            // buracos estruturais da cobertura e manda conferir o `tipo` — e a
+            // descrição da tool promete esse formato. O ganho da borda nova chega
+            // mesmo assim: rota montada errada agora falha alto em vez de virar
+            // "sem notas".
+            () => upstreamFetch(path, {}, baseUrl, { on404: "empty" }));
             const nt = response?.notasTaquigraficas ?? response;
             const quartosTodos = ensureArray(nt?.quartos);
             let quartos = quartosTodos;
@@ -147,8 +155,9 @@ export function registerTaquigrafiaTools(server, baseUrl) {
             const tipo = params.tipo ?? "sessao";
             const path = `/taquigrafia/videos/${tipo}/${params.id}`;
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_videos_taquigrafia", { tipo, id: params.id }, CACHE_ON_DEMAND, 
-            // Same 404-as-empty posture as the notes acervo (missing media -> 404).
-            () => upstreamFetch(path, {}, baseUrl, { treat404AsEmpty: true }));
+            // Same 404-as-empty posture as the notes acervo (missing media -> 404),
+            // e pelo mesmo motivo: o zero aqui fala, via VIDEOS_TAQUIGRAFIA_AVISO_VAZIO.
+            () => upstreamFetch(path, {}, baseUrl, { on404: "empty" }));
             const videosTodos = ensureArray(response).map(parseVideoUnidade);
             let videos = videosTodos;
             if (params.orador) {

package/dist/tools/votacoes.js

@@ -9,7 +9,7 @@
 import { z } from "zod";
 import { cachedFetchWithMeta } from "../cache/manager.js";
 import { upstreamFetch } from "../throttle/upstream.js";
-import { errorFrom, buildParams, ensureArray } from "../utils/validation.js";
+import { toolError, errorFrom, buildParams, ensureArray } from "../utils/validation.js";
 import { computarPlacar } from "../utils/placar.js";
 import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { CACHE_ON_DEMAND } from "../types.js";
@@ -86,23 +86,89 @@ export function parseVotacaoItem(v, includeVotos = false) {
     }
     return result;
 }
+/**
+ * Os DOIS espaços de numeração que o item de `/votacao` carrega ao mesmo tempo.
+ *
+ * | campo da fonte        | exemplo  | o que é                          |
+ * |-----------------------|----------|----------------------------------|
+ * | `codigoSessao`        | 581816   | a sessão plenária (6 dígitos)    |
+ * | `codigoSessaoVotacao` | 7101     | a votação dentro dela (4 dígitos)|
+ *
+ * `/votacao` só filtra pelo primeiro: medido em 24/09/2026,
+ * `?codigoSessao=581816` devolve 3 votações e 81 votos nominais, enquanto
+ * `?codigoSessao=7101` devolve `[]`. E a fonte **ignora filtro desconhecido**
+ * em vez de recusá-lo — `?codigoSessaoVotacao=7101` devolve a base inteira
+ * (1,77 MB) —, então não existe filtro server-side pelo código da votação:
+ * resolver é do nosso lado ([[esquema-que-nao-recusa-responde-outra-pergunta]]).
+ */
+export const CAMPO_SESSAO = "codigoSessao";
+export const CAMPO_VOTACAO = "codigoSessaoVotacao";
+/**
+ * Acha, numa lista crua de `/votacao`, o item cujo `codigoSessaoVotacao` é
+ * `codigo`. Devolve `undefined` quando não está na janela.
+ *
+ * Existe separada do handler para a guarda poder exercitá-la sem montar URL —
+ * o conferidor não pode reusar o caminho do defeito
+ * ([[guarda-que-reusa-o-padrao-do-defeito]]).
+ */
+export function acharPorCodigoVotacao(lista, codigo) {
+    return ensureArray(lista).find((v) => {
+        const bruto = v?.[CAMPO_VOTACAO];
+        if (bruto === null || bruto === undefined || bruto === "")
+            return false;
+        return Number(bruto) === codigo;
+    });
+}
 export function registerVotacoesTools(server, baseUrl) {
     // D3. senado_obter_votacao
-    server.tool("senado_obter_votacao", "Obtém detalhes de uma votação de **plenário** pelo `codigoVotacao` (que é o `codigoSessao` da sessão plenária), incluindo votos nominais. Retorna o objeto da votação (placar, `resultado` legível + `resultadoCodigo` bruto, `secreta`) com `votos[]` (`codigoSenador`, `nomeSenador`, `partido`, `uf`, `voto`); se a sessão tiver várias votações, retorna `{ codigoSessao, count, votacoes }`. Obtenha o `codigoSessao` via `senado_search_votacoes` antes de chamar. Atenção: este endpoint só aceita códigos de votação de **plenário** — códigos de `senado_votacao_comissao` pertencem a outro espaço de numeração e NÃO são válidos aqui (podem coincidir numericamente, mas apontam para outra votação).", {
-        codigoVotacao: z.number().int().positive().describe("Código único da votação (codigoSessao da sessão plenária)"),
+    server.tool("senado_obter_votacao", "Obtém detalhes de uma votação de **plenário**, incluindo votos nominais. `codigoVotacao` aceita OS DOIS códigos que a fonte publica para a mesma votação: o `codigoVotacao` de 4 dígitos (ex.: 7101 — o que `senado_search_votacoes` e `senado_votacoes_senador` devolvem nesse campo) ou o `codigoSessao` de 6 dígitos da sessão plenária (ex.: 581816). Com o código da votação retorna aquela votação; com o da sessão retorna `{ codigoSessao, count, votacoes }` com todas as votações da sessão. Cada votação traz placar, `resultado` legível + `resultadoCodigo` bruto, `secreta` e `votos[]` (`codigoSenador`, `nomeSenador`, `partido`, `uf`, `voto`). Resolver o código de 4 dígitos exige varrer uma janela temporal: por padrão a janela recente da fonte (~12 meses); para votação mais antiga informe `ano`. Código que não existe em nenhum dos dois espaços retorna erro — nunca lista vazia. Atenção: códigos de `senado_votacao_comissao` e o `codigoVotacao` de `senado_orientacao_bancada` pertencem a OUTROS espaços de numeração e não são válidos aqui.", {
+        codigoVotacao: z.number().int().positive().describe("Código da votação (4 dígitos, ex. 7101) OU o codigoSessao da sessão plenária (6 dígitos, ex. 581816) — os dois são aceitos"),
+        ano: z.number().int().min(1990).max(2100).optional().describe("Só para código de votação de 4 dígitos ANTERIOR aos últimos ~12 meses: o ano em que a votação ocorreu, para abrir a janela de busca"),
     }, async (params) => {
         try {
-            const qp = { codigoSessao: String(params.codigoVotacao) };
-            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_obter_votacao", { codigo: params.codigoVotacao }, CACHE_ON_DEMAND, () => upstreamFetch("/votacao", qp, baseUrl));
+            const codigo = params.codigoVotacao;
+            // PASSO 1 — tentar como codigoSessao, o ÚNICO filtro que a fonte honra.
+            const qp = { [CAMPO_SESSAO]: String(codigo) };
+            const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_obter_votacao", { codigo }, CACHE_ON_DEMAND, () => upstreamFetch("/votacao", qp, baseUrl));
             const votacoes = ensureArray(response).map((v) => parseVotacaoItem(v, true));
-            const prov = provenanceFor("SENADO_LEGIS", baseUrl, "/votacao", {
-                dataset_id: `codigoSessao=${params.codigoVotacao}`,
-                reference_period: votacoes[0]?.data || undefined,
-                retrieved_at: fetchedAt,
-            });
-            if (votacoes.length === 1)
-                return resultWithProvenance(votacoes[0], prov);
-            return resultWithProvenance({ codigoSessao: params.codigoVotacao, count: votacoes.length, votacoes }, prov);
+            if (votacoes.length > 0) {
+                const prov = provenanceFor("SENADO_LEGIS", baseUrl, "/votacao", {
+                    dataset_id: `${CAMPO_SESSAO}=${codigo}`,
+                    reference_period: votacoes[0]?.data || undefined,
+                    retrieved_at: fetchedAt,
+                });
+                if (votacoes.length === 1)
+                    return resultWithProvenance(votacoes[0], prov);
+                return resultWithProvenance({ codigoSessao: codigo, count: votacoes.length, votacoes }, prov);
+            }
+            // PASSO 2 — vazio não é resposta: o número pode ser do OUTRO espaço.
+            // Até 24/09/2026 o handler paravaaqui e devolvia `{count: 0}` — para
+            // 7101, que é a votação do PLP 124/2022 com 69 Sim. Pior que zero
+            // calado: indistinguível do zero de um id inventado.
+            const janela = params.ano
+                ? { dataInicio: `${params.ano}-01-01`, dataFim: `${params.ano}-12-31` }
+                : {};
+            const { value: cru, fetchedAt: fetchedAtJanela } = await cachedFetchWithMeta("senado_obter_votacao_janela", janela, CACHE_ON_DEMAND, () => upstreamFetch("/votacao", janela, baseUrl));
+            const achado = acharPorCodigoVotacao(cru, codigo);
+            if (achado) {
+                const votacao = parseVotacaoItem(achado, true);
+                return resultWithProvenance(votacao, provenanceFor("SENADO_LEGIS", baseUrl, "/votacao", {
+                    dataset_id: `${CAMPO_VOTACAO}=${codigo}`,
+                    reference_period: votacao.data || undefined,
+                    retrieved_at: fetchedAtJanela,
+                }));
+            }
+            // PASSO 3 — não está em nenhum dos dois espaços: ausência TIPADA.
+            const ondeProcurou = params.ano
+                ? `no ano ${params.ano}`
+                : "na janela recente da fonte (~12 meses)";
+            return toolError(`Não existe votação de plenário com o código ${codigo}: ele não é ` +
+                `codigoSessao de nenhuma sessão nem codigoVotacao ${ondeProcurou}.` +
+                (params.ano
+                    ? " Confira o ano e o código em senado_search_votacoes."
+                    : " Se a votação é anterior, informe o `ano`; ou obtenha o código em" +
+                        " senado_search_votacoes. O `codigoVotacao` de senado_orientacao_bancada" +
+                        " pertence a outro espaço de numeração e não é aceito aqui."));
         }
         catch (e) {
             return errorFrom(e, "Votação não encontrada");

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Single source of truth for the server version (kept in sync with package.json). */
-export const VERSION = "3.9.0";
+export const VERSION = "3.10.0";
 export const USER_AGENT = `senado-br-mcp/${VERSION} (+https://senado.sidneybissoli.com; sbissoli76@gmail.com)`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "senado-br-mcp",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,8 @@
     "build:dataset": "tsx scripts/build-dataset/index.ts",
     "dataset:dictionary": "tsx scripts/build-dataset/index.ts --dictionary-only",
     "release:dataset": "tsx scripts/build-dataset/release.ts",
-    "release:zenodo": "tsx scripts/build-dataset/zenodo-publish.ts"
+    "release:zenodo": "tsx scripts/build-dataset/zenodo-publish.ts",
+    "manifest:lhm": "node scripts/gen-lhm-manifest.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",