senado-br-mcp 3.18.5 → 3.19.0

package/README.md

@@ -565,7 +565,7 @@ Fields of the `concise` block (contract v1.3 since 3.18.5; per response — one
 | `citation` | Ready-to-use citation string (human-readable) |
 | `license` | Source terms (Dados Abertos do Senado Federal) |
 | `field_sources` | *Optional.* Per-field sub-sources, each with its own extraction instant — only on responses that merge reads (v1.2, since 3.17.0; see below) |
-| `derived` / `derivation_note` | *Optional.* `true` + a fixed note when the server computed the values — the `estatisticas` modes (distribution, aggregates, rankings) of `senado_remuneracoes_servidores`, `senado_horas_extras`, `senado_ceaps`, `senado_execucao_orcamentaria` and `senado_suprimento_fundos`; the individual values they cite remain the Senate's own |
+| `derived` / `derivation_note` | *Optional.* `true` + a fixed pt-BR note naming the calculation whenever the server computed values instead of copying them (since 3.19.0, the whole class): the `estatisticas` modes (distribution, aggregates, rankings); group sums, counts and averages — CEAPS `valorTotal` and its per-senator/type/month/supplier modes, the budget execution aggregates (`por-ano`, the default, included), the payroll `resumo`, the overtime `valorTotal`, the `relatoria` distribution, seated senators per party/UF, the historical e-Cidadania national totals; the payroll gross (`bruto`, sum of seven components); servants assigned to an org subtree (`subordinadasA`); a vote tally counted from nominal votes when the source publishes none (plenary open roll calls, committee votes without totals); e-Cidadania percentages, consensus/polarisation rankings and the estimated idea creation date; the current legislature's period. Absent when every number is the source's own (raw lists, `detalhe` of the budget, published tallies). The individual values cited remain the Senate's |
 | `revision` | Whether the figure may still change at the source: `status` is `current` for every Senate source (the version in force at extraction; none is claimed `final`), and `note` says, for the administrative and budget sources, that the Senate may correct published data later |
 
 No Senate source publishes notices alongside the data, so `notices` (also part of v1.3) does not appear. The text footer gains a line only for exceptions — here, the computed-values line on the `estatisticas` modes.

package/dist/tools/comissoes.js

@@ -17,7 +17,7 @@ import { upstreamFetch, UpstreamError } from "../throttle/upstream.js";
 import { toolError, errorFrom, ensureArray, safeInt, toBool, normalizeText } from "../utils/validation.js";
 import { digArrayRoot } from "../utils/upstream-parse.js";
 import { escolherReuniao, ehReuniaoInexistente, mensagemCodigoInexistente } from "./resolver-reuniao.js";
-import { leituraDoCache, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { NOTA_DERIVACAO_SOMAS, derivadoSe, leituraDoCache, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { CACHE_SEMI_STATIC, CACHE_DYNAMIC, CACHE_ON_DEMAND } from "../types.js";
 export function formatDateYMD(d) {
     return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, "0")}${String(d.getDate()).padStart(2, "0")}`;
@@ -154,6 +154,12 @@ export function provenanceReunioesComissao(baseUrl, sigla, di, df, partes) {
             : {}),
     });
 }
+/**
+ * `senado_distribuicao_materias` (contract v1.3): in `relatoria` the source sends one row per
+ * (parlamentar, unidade) and the server sums `Quantidade` per parlamentar — derived; in `autoria`
+ * each count is the source's own (ordering only).
+ */
+export const provenanceDaDistribuicao = (prov, tipo) => derivadoSe(prov, tipo === "relatoria", NOTA_DERIVACAO_SOMAS);
 export function registerComissoesTools(server, baseUrl) {
     // E1. senado_listar_comissoes
     server.tool("senado_listar_comissoes", "Lista comissões (colegiados) ativas do Senado, com filtros por `tipo` (permanente, temporaria, cpi, mista) e `ativa`. Retorna `{ count, comissoes }`, cada item com `codigo`, `sigla`, `nome`, `tipo`, `casa` e `ativa`. O endpoint só traz comissões ativas, logo `ativa=false` resulta em lista vazia. Use para descobrir a `sigla` exigida por `senado_obter_comissao` e `senado_reunioes_comissao`.", {
@@ -554,7 +560,7 @@ export function registerComissoesTools(server, baseUrl) {
                 tipo,
                 count: parlamentares.length,
                 parlamentares,
-            }, prov);
+            }, provenanceDaDistribuicao(prov, tipo));
         }
         catch (e) {
             return errorFrom(e, "Erro ao obter distribuição de matérias");

package/dist/tools/ecidadania.js

@@ -12,7 +12,7 @@
 import { z } from "zod";
 import { cachedFetchWithMeta } from "../cache/manager.js";
 import { errorFrom } from "../utils/validation.js";
-import { leituraDoCache, provenanceEcidadania, provenanceArquimedesVotos, resultWithProvenance, withFieldSources, } from "../utils/provenance.js";
+import { leituraDoCache, provenanceEcidadania, NOTA_DERIVACAO_DATA_ESTIMADA, NOTA_DERIVACAO_PERCENTUAIS, NOTA_DERIVACAO_RANKING_ECIDADANIA, NOTA_DERIVACAO_SOMAS, derivado, derivadoSe, provenanceArquimedesVotos, resultWithProvenance, withFieldSources, } from "../utils/provenance.js";
 import { tagUntrustedFields, tagUntrustedList, neutralizeUntrustedText, sanitizeScrapedText } from "../utils/untrusted.js";
 import { CACHE_ON_DEMAND } from "../types.js";
 import { resolveList, writeDetalheThrough } from "../scraper/store.js";
@@ -90,6 +90,18 @@ export function provenanceEventoDetalhe(item, id, leitura, corpusMeta) {
         subFonteDoCorpus("/principalaudiencia", "eventos", corpusMeta, ["comentarios"]),
     ]);
 }
+/**
+ * Contract v1.3 `derived` on e-Cidadania responses. Every consulta carries percentages the server
+ * computes (`buildConsultaResumo`), and `totalVotos` too when the source sends no total; the
+ * analysis and the poll suggestion add their own polarisation/consensus metrics and ranking on top;
+ * an idea's creation date is an estimate; the historical archive's national totals are summed from
+ * the per-UF rows of the CSV.
+ */
+export const NOTA_DERIVACAO_ANALISE_CONSULTAS = `${NOTA_DERIVACAO_RANKING_ECIDADANIA} ${NOTA_DERIVACAO_PERCENTUAIS}`;
+export const provenanceDasConsultas = (prov) => derivado(prov, NOTA_DERIVACAO_PERCENTUAIS);
+export const provenanceDaAnaliseDeConsultas = (prov) => derivado(prov, NOTA_DERIVACAO_ANALISE_CONSULTAS);
+export const provenanceDasIdeias = (prov, ideias) => derivadoSe(prov, ideias.some((i) => i.dataCriacaoEstimada != null), NOTA_DERIVACAO_DATA_ESTIMADA);
+export const provenanceDosVotosHistoricos = (prov) => derivado(prov, NOTA_DERIVACAO_SOMAS);
 /**
  * Proveniência de `senado_ecidadania_sugerir_tema_enquete`: as sugestões cruzam DOIS corpora
  * do D1 (consultas e ideias), cada um com o seu `lastScrapedAt`. Até a 3.18.1 o topo levava só
@@ -103,10 +115,10 @@ export function provenanceSugestaoEnquete(consultasMeta, ideiasMeta) {
         dataset_id: "consultas+ideias",
         retrieved_at: typeof ts === "string" && ts ? ts : undefined,
     });
-    return withFieldSources(prov, [
+    return derivado(withFieldSources(prov, [
         subFonteDoCorpus("/principalmateria", "consultas", consultasMeta, campos),
         subFonteDoCorpus("/principalideia", "ideias", ideiasMeta, campos),
-    ]);
+    ]), NOTA_DERIVACAO_ANALISE_CONSULTAS);
 }
 // ══════════════════════════════════════════════════════════════════════════
 // Tool registration
@@ -158,7 +170,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
             const limite = params.limite ?? 20;
             const offset = ((params.pagina ?? 1) - 1) * limite;
             const out = filtered.slice(offset, offset + limite);
-            return resultWithProvenance({ count: out.length, consultas: tagUntrustedList("consultas", out), meta }, provLista("/principalmateria", "consultas", meta));
+            return resultWithProvenance({ count: out.length, consultas: tagUntrustedList("consultas", out), meta }, provenanceDasConsultas(provLista("/principalmateria", "consultas", meta)));
         }
         catch (e) {
             return ecidadaniaError(e);
@@ -170,7 +182,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
             const { value: r, fetchedAt } = await cachedFetchWithMeta("ecidadania_consulta", { id: params.id }, CACHE_ON_DEMAND, () => obterConsultaInternal(params.id));
             writeDetalheThrough(db, ctx, "consultas", params.id, r);
             const detalhe = buildConsultaDetalheResult(r);
-            return resultWithProvenance(tagUntrustedFields("consultas", detalhe), provDetalhe(r, `/visualizacaomateria?id=${params.id}`, `consulta=${params.id}`, fetchedAt));
+            return resultWithProvenance(tagUntrustedFields("consultas", detalhe), provenanceDasConsultas(provDetalhe(r, `/visualizacaomateria?id=${params.id}`, `consulta=${params.id}`, fetchedAt)));
         }
         catch (e) {
             return ecidadaniaError(e);
@@ -216,7 +228,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
                     .slice(0, limite);
                 criterio = `≥${percentualMinimo}% numa direção, mínimo ${minimoVotos} votos`;
             }
-            return resultWithProvenance({ modo, criterio, count: filtered.length, consultas: tagUntrustedList("consultas", filtered), meta }, provLista("/principalmateria", "consultas", meta));
+            return resultWithProvenance({ modo, criterio, count: filtered.length, consultas: tagUntrustedList("consultas", filtered), meta }, provenanceDaAnaliseDeConsultas(provLista("/principalmateria", "consultas", meta)));
         }
         catch (e) {
             return ecidadaniaError(e);
@@ -248,7 +260,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
                 ideias: tagUntrustedList("ideias", ideias),
                 avisoDatas: AVISO_DATAS_IDEIA,
                 meta,
-            }, provLista("/principalideia", "ideias", meta));
+            }, provenanceDasIdeias(provLista("/principalideia", "ideias", meta), ideias));
         }
         catch (e) {
             return ecidadaniaError(e);
@@ -269,7 +281,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
                 comentarios: null,
                 avisoDatas: AVISO_DATAS_IDEIA,
             };
-            return resultWithProvenance(tagUntrustedFields("ideias", detalhe), provDetalhe(r, `/visualizacaoideia?id=${params.id}`, `ideia=${params.id}`, fetchedAt));
+            return resultWithProvenance(tagUntrustedFields("ideias", detalhe), provenanceDasIdeias(provDetalhe(r, `/visualizacaoideia?id=${params.id}`, `ideia=${params.id}`, fetchedAt), [detalhe]));
         }
         catch (e) {
             return ecidadaniaError(e);
@@ -474,10 +486,10 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
             if (out.length === 0 && (meta.fonte === "ao-vivo" || meta.motivo === "d1-vazio" || meta.motivo === "d1-indisponivel")) {
                 payload.aviso = "Acervo de votos ainda não ingerido (primeira carga semanal pendente) ou filtro sem correspondência.";
             }
-            return resultWithProvenance(payload, provenanceArquimedesVotos({
+            return resultWithProvenance(payload, provenanceDosVotosHistoricos(provenanceArquimedesVotos({
                 reference_period: referencePeriod ?? undefined,
                 retrieved_at: typeof meta.lastScrapedAt === "string" && meta.lastScrapedAt ? meta.lastScrapedAt : undefined,
-            }));
+            })));
         }
         catch (e) {
             return ecidadaniaError(e);

package/dist/tools/orcamento-senado.js

@@ -13,7 +13,7 @@ import { z } from "zod";
 import { cachedFetchWithMeta } from "../cache/manager.js";
 import { upstreamFetch } from "../throttle/upstream.js";
 import { errorFrom, ensureArray, safeInt, parseBRL } from "../utils/validation.js";
-import { derivadoDeEstatisticas, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { NOTA_DERIVACAO_SOMAS, derivadoDeEstatisticas, derivadoSe, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { computarEstatisticas, arredondarEstatisticas, arredondarEntradas, } from "../utils/estatisticas.js";
 import { CACHE_STATIC } from "../types.js";
 const FINANCEIRO_BASE = "https://www.senado.gov.br";
@@ -80,6 +80,8 @@ export function parseReceita(r) {
     };
 }
 /** Aggregate normalized despesas by a key, summing the five value columns. */
+/** Todo modo fora de `detalhe` soma por grupo (por-ano, o padrão, também): é cálculo do servidor. */
+export const provenanceDaExecucao = (prov, modo) => derivadoSe(prov, modo !== "detalhe", NOTA_DERIVACAO_SOMAS);
 export function agregarDespesas(itens, chave) {
     const grupos = new Map();
     for (const d of itens) {
@@ -272,7 +274,7 @@ export function registerOrcamentoSenadoTools(server) {
                         agregado = agregado.sort((a, b) => String(a.chave).localeCompare(String(b.chave)));
                     resultado = { agregado: agregado.slice(0, limite) };
                 }
-                return resultWithProvenance({ tipo, modo, ano: params.ano ?? null, totalLinhas: itens.length, ...resultado }, prov);
+                return resultWithProvenance({ tipo, modo, ano: params.ano ?? null, totalLinhas: itens.length, ...resultado }, provenanceDaExecucao(prov, modo));
             }
             // receitas
             let itens = ensureArray(bruto?.receitas).map(parseReceita);
@@ -303,7 +305,7 @@ export function registerOrcamentoSenadoTools(server) {
                     : agregado.sort((a, b) => a.chave.localeCompare(b.chave));
                 resultado = { agregado: agregado.slice(0, limite) };
             }
-            return resultWithProvenance({ tipo, modo, ano: params.ano ?? null, totalLinhas: itens.length, ...resultado }, prov);
+            return resultWithProvenance({ tipo, modo, ano: params.ano ?? null, totalLinhas: itens.length, ...resultado }, provenanceDaExecucao(prov, modo));
         }
         catch (e) {
             return errorFrom(e, "Erro ao consultar execução orçamentária");

package/dist/tools/referencia.js

@@ -9,7 +9,7 @@ import { cachedFetchWithMeta } from "../cache/manager.js";
 import { upstreamFetch } from "../throttle/upstream.js";
 import { errorFrom, ensureArray } from "../utils/validation.js";
 import { digArrayRoot } from "../utils/upstream-parse.js";
-import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { NOTA_DERIVACAO_LEGISLATURA, NOTA_DERIVACAO_LEGISLATURA_PADRAO, NOTA_DERIVACAO_SOMAS, derivado, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { CACHE_STATIC } from "../types.js";
 export const TIPOS_MATERIA = [
     { sigla: "PEC", nome: "Proposta de Emenda à Constituição", descricao: "Altera a Constituição Federal" },
@@ -64,6 +64,15 @@ export function deriveLegislaturaAtual(parlamentares) {
     // Fallback to the 57th legislatura (2023-2027)
     return { numero: 57, periodo: "2023-2027", dataInicio: "2023-02-01", dataFim: "2027-01-31" };
 }
+/**
+ * `tabela=legislatura-atual` (contract v1.3): period and dates are always the server's arithmetic;
+ * when the source sends no legislatura number the number itself is the server's fallback, and the
+ * note says so.
+ */
+export function provenanceDaLegislatura(prov, parlamentares) {
+    const doFonte = Boolean(parlamentares[0]?.Mandato?.PrimeiraLegislaturaDoMandato?.NumeroLegislatura);
+    return derivado(prov, doFonte ? NOTA_DERIVACAO_LEGISLATURA : NOTA_DERIVACAO_LEGISLATURA_PADRAO);
+}
 /** Tally seated senators per party (sigla → count). */
 export function tabularPartidos(parlamentares) {
     const counts = {};
@@ -125,7 +134,7 @@ export function registerReferenciaTools(server, baseUrl) {
                     const prov = provenanceFor("SENADO_LEGIS", baseUrl, "/senador/lista/atual", {
                         dataset_id: "tabela=partidos", retrieved_at: fetchedAt,
                     });
-                    return resultWithProvenance({ tabela: params.tabela, count: partidos.length, totalSenadores: parlamentares.length, partidos }, prov);
+                    return resultWithProvenance({ tabela: params.tabela, count: partidos.length, totalSenadores: parlamentares.length, partidos }, derivado(prov, NOTA_DERIVACAO_SOMAS));
                 }
                 case "ufs": {
                     const { value, fetchedAt } = await fetchSenadoresAtuais(baseUrl);
@@ -134,7 +143,7 @@ export function registerReferenciaTools(server, baseUrl) {
                     const prov = provenanceFor("SENADO_LEGIS", baseUrl, "/senador/lista/atual", {
                         dataset_id: "tabela=ufs", retrieved_at: fetchedAt,
                     });
-                    return resultWithProvenance({ tabela: params.tabela, count: ufs.length, totalSenadores: parlamentares.length, ufs }, prov);
+                    return resultWithProvenance({ tabela: params.tabela, count: ufs.length, totalSenadores: parlamentares.length, ufs }, derivado(prov, NOTA_DERIVACAO_SOMAS));
                 }
                 case "legislatura-atual": {
                     const { value, fetchedAt } = await fetchSenadoresAtuais(baseUrl);
@@ -142,7 +151,7 @@ export function registerReferenciaTools(server, baseUrl) {
                     const prov = provenanceFor("SENADO_LEGIS", baseUrl, "/senador/lista/atual", {
                         dataset_id: "tabela=legislatura-atual", retrieved_at: fetchedAt,
                     });
-                    return resultWithProvenance({ tabela: params.tabela, ...deriveLegislaturaAtual(parlamentares) }, prov);
+                    return resultWithProvenance({ tabela: params.tabela, ...deriveLegislaturaAtual(parlamentares) }, provenanceDaLegislatura(prov, parlamentares));
                 }
                 case "tipos-norma": {
                     const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_tipos_norma", {}, CACHE_STATIC, () => upstreamFetch("/legislacao/tiposNorma", {}, baseUrl));

package/dist/tools/senadores-admin.js

@@ -12,7 +12,7 @@ import { cachedFetchWithMeta } from "../cache/manager.js";
 import { admFetch, admFetchLarge } from "../throttle/adm.js";
 import { errorFrom, ensureArray, normalizeText, parseBRL } from "../utils/validation.js";
 import { unwrapAdmEnvelope } from "../utils/upstream-parse.js";
-import { derivadoDeEstatisticas, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { NOTA_DERIVACAO_SOMAS, derivado, derivadoDeEstatisticas, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { computarEstatisticas, arredondarEstatisticas, arredondarEntradas, } from "../utils/estatisticas.js";
 import { CACHE_SEMI_STATIC, CACHE_STATIC } from "../types.js";
 const norm = normalizeText;
@@ -40,6 +40,8 @@ export function filtrarCeaps(itens, f) {
     });
 }
 /** Aggregate CEAPS items by a key extractor. */
+/** Toda resposta fora de `estatisticas` leva `valorTotal` (soma do servidor), em qualquer modo. */
+export const provenanceDoCeaps = (prov) => derivado(prov, NOTA_DERIVACAO_SOMAS);
 export function agregarCeaps(itens, chave, extra) {
     const grupos = new Map();
     for (const d of itens) {
@@ -186,7 +188,7 @@ export function registerSenadoresAdminTools(server, admBaseUrl) {
                 totalDespesas: filtrado.length,
                 valorTotal: totalGeral,
                 ...resultado,
-            }, prov);
+            }, provenanceDoCeaps(prov));
         }
         catch (e) {
             return errorFrom(e, "Erro ao consultar despesas CEAPS");

package/dist/tools/servidores.js

@@ -12,7 +12,7 @@ import { cachedFetchWithMeta } from "../cache/manager.js";
 import { admFetch, admFetchLarge } from "../throttle/adm.js";
 import { errorFrom, ensureArray, parseBRL } from "../utils/validation.js";
 import { unwrapAdmEnvelope } from "../utils/upstream-parse.js";
-import { derivadoDeEstatisticas, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { NOTA_DERIVACAO_BRUTO, NOTA_DERIVACAO_SOMAS, NOTA_DERIVACAO_SUBORDINADAS, derivado, derivadoDeEstatisticas, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { computarEstatisticas, arredondarEstatisticas, arredondarEntradas, } from "../utils/estatisticas.js";
 import { CACHE_SEMI_STATIC, CACHE_STATIC } from "../types.js";
 import { matchesFiltro, matchesFiltroCampo } from "./contratacoes.js";
@@ -55,6 +55,16 @@ export function resumoRemuneracao(r) {
             num(r.gratificacao_natalina) + num(r.horas_extras) + num(r.outras_eventuais) + num(r.abono_permanencia)) * 100) / 100,
     };
 }
+/**
+ * Provenance of the non-statistics remuneration modes (contract v1.3): `detalhe` carries the
+ * server-summed `bruto` per row; `resumo` (the default) sums and averages that `bruto` per
+ * `tipoFolha`, so its note names both calculations.
+ */
+export const provenanceDaRemuneracao = (prov, modo) => modo === "detalhe"
+    ? derivado(prov, NOTA_DERIVACAO_BRUTO)
+    : derivado(prov, `${NOTA_DERIVACAO_SOMAS} ${NOTA_DERIVACAO_BRUTO}`);
+/** Overtime outside `estatisticas`: `valorTotal` at the top is the server's sum of the rows. */
+export const provenanceDasHorasExtras = (prov) => derivado(prov, NOTA_DERIVACAO_SOMAS);
 /** The 7 columns that sum into `bruto` (identical composition to `resumoRemuneracao`). */
 const COMPONENTES_BRUTO = [
     "remuneracaoBasica", "vantagensPessoais", "funcaoComissionada", "gratificacaoNatalina",
@@ -348,7 +358,7 @@ export function particionarPorUnidade(lista, indice, codUnidade) {
  * busca, então a sub-fonte dele não diz (`served_from_cache: null`).
  */
 export function provenanceServidoresSubordinadas(prov, situacao, folhaDoCache) {
-    return withFieldSources(prov, [
+    return derivado(withFieldSources(prov, [
         {
             fields: ["servidores", "total", "count", "naoClassificados", "afastadosOuEmTransito"],
             source_url: prov.source_url,
@@ -363,7 +373,7 @@ export function provenanceServidoresSubordinadas(prov, situacao, folhaDoCache) {
             reference_period: ESTRUTURA_VINTAGE.slice(0, 10),
             retrieved_at: ESTRUTURA_VINTAGE,
         },
-    ]);
+    ]), NOTA_DERIVACAO_SUBORDINADAS);
 }
 export function registerServidoresTools(server, admBaseUrl) {
     // P1. senado_servidores
@@ -484,7 +494,7 @@ export function registerServidoresTools(server, admBaseUrl) {
                     total: itens.length,
                     ...(itens.length > limite ? { aviso: `Exibindo ${limite} de ${itens.length} registros. Filtre por nome ou use modo=resumo.` } : {}),
                     remuneracoes: itens.slice(0, limite).map(resumoRemuneracao),
-                }, prov);
+                }, provenanceDaRemuneracao(prov, "detalhe"));
             }
             const porFolha = new Map();
             for (const r of itens) {
@@ -503,7 +513,7 @@ export function registerServidoresTools(server, admBaseUrl) {
                 mediaBruta: Math.round((g.totalBruto / g.registros) * 100) / 100,
             }))
                 .sort((a, b) => b.totalBruto - a.totalBruto);
-            return resultWithProvenance({ ano: params.ano, mes: params.mes, totalRegistros: itens.length, resumo }, prov);
+            return resultWithProvenance({ ano: params.ano, mes: params.mes, totalRegistros: itens.length, resumo }, provenanceDaRemuneracao(prov, "resumo"));
         }
         catch (e) {
             return errorFrom(e, "Erro ao consultar remunerações");
@@ -548,7 +558,7 @@ export function registerServidoresTools(server, admBaseUrl) {
                 total: itens.length,
                 valorTotal,
                 horasExtras: itens.slice(0, limite),
-            }, prov);
+            }, provenanceDasHorasExtras(prov));
         }
         catch (e) {
             return errorFrom(e, "Erro ao consultar horas extras");

package/dist/tools/votacao-comissao.js

@@ -7,14 +7,14 @@ import { cachedFetchWithMeta } from "../cache/manager.js";
 import { upstreamFetch } from "../throttle/upstream.js";
 import { toolError, errorFrom, buildParams, ensureArray, normalizeText } from "../utils/validation.js";
 import { digArrayRoot } from "../utils/upstream-parse.js";
-import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { NOTA_DERIVACAO_PLACAR_COMISSAO, derivadoSe, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { CACHE_DYNAMIC } from "../types.js";
 const VOTACAO_COMISSAO_ROOT = [["VotacoesComissao", "Votacoes", "Votacao"]];
 /** Parse a committee vote item (VotacoesComissao.Votacoes.Votacao[]). */
 export function parseVotacaoComissao(v) {
     const votacao = v.Votacao || v;
     const votosRaw = ensureArray(votacao.Votos?.Voto ?? votacao.votos);
-    let totalSim = 0, totalNao = 0, totalAbstencao = 0;
+    let totalSim = 0, totalNao = 0, totalAbstencao = 0; // recontagem, usada só se a fonte não publicar
     const votos = votosRaw.map((vt) => {
         const q = normalizeText(vt.QualidadeVoto || vt.DescricaoVoto || vt.voto);
         if (q === "s" || q === "sim")
@@ -37,10 +37,35 @@ export function parseVotacaoComissao(v) {
         reuniao: votacao.CodigoReuniao || null,
         materia: votacao.IdentificacaoMateria || votacao.DescricaoIdentificacaoMateria || null,
         descricao: votacao.DescricaoVotacao || votacao.descricaoVotacao || null,
-        totalSim, totalNao, totalAbstencao,
+        ...placarDaComissao(votacao, { sim: totalSim, nao: totalNao, abstencao: totalAbstencao }),
         votos,
     };
 }
+const totalPublicado = (v) => {
+    if (v === undefined || v === null || v === "")
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+};
+/**
+ * Committee tally: the source's `TotalVotosSim/Nao/Abstencao` when it publishes them (it does on
+ * every vote measured — 395 of 395 at the CCJ on 15/10/2026), the recount of the nominal votes
+ * only when all three are missing, then flagged `placarComputado`. Until 3.18.5 the parser always
+ * recounted, and 5 of those 395 came out different from the published tally: the source repeats
+ * the nominal list in some votes (24/25 counted against 12/13 published) and counts an "A" vote
+ * as no abstention in others. The published number is the source's own; the recount is not.
+ */
+export function placarDaComissao(votacao, recontagem) {
+    const sim = totalPublicado(votacao?.TotalVotosSim);
+    const nao = totalPublicado(votacao?.TotalVotosNao);
+    const abstencao = totalPublicado(votacao?.TotalVotosAbstencao);
+    if (sim !== null || nao !== null || abstencao !== null) {
+        return { totalSim: sim ?? 0, totalNao: nao ?? 0, totalAbstencao: abstencao ?? 0 };
+    }
+    return { totalSim: recontagem.sim, totalNao: recontagem.nao, totalAbstencao: recontagem.abstencao, placarComputado: true };
+}
+/** `derived` (contract v1.3) only when some item's tally had to be counted from the votes. */
+export const provenanceDaVotacaoComissao = (prov, votacoes) => derivadoSe(prov, votacoes.some((v) => v.placarComputado === true), NOTA_DERIVACAO_PLACAR_COMISSAO);
 /**
  * Filter parsed committee votes locally by reunion date. The upstream serves the full
  * history regardless of the date query params, so the window is enforced in-Worker.
@@ -66,7 +91,7 @@ export function registerVotacaoComissaoTools(server, baseUrl) {
         "`por: comissao` → exige `siglaComissao`; lista as votações daquela comissão. " +
         "`por: senador` → exige `codigoSenador`; lista os votos do senador em comissões (filtro opcional `comissao`). " +
         "`por: materia` → exige `sigla`, `numero` e `ano` (ex.: PL 2630/2020); lista as votações da proposição em comissões (filtro opcional `comissao`). " +
-        "Em todos os casos aceita período opcional `dataInicio`/`dataFim` (YYYYMMDD, filtrado pela data da reunião) e retorna `{ por, ...contexto, count, votacoes }`, cada votação com `codigo`, `data`, `comissao`, `reuniao`, `materia`, `descricao`, totais computados dos votos (`totalSim`/`totalNao`/`totalAbstencao`) e `votos` (senador, partido, voto). Sem paginação. Períodos amplos podem estourar o tempo-limite da consulta (erro de timeout): prefira janelas de até 3 meses e divida períodos maiores em chamadas sucessivas. " +
+        "Em todos os casos aceita período opcional `dataInicio`/`dataFim` (YYYYMMDD, filtrado pela data da reunião) e retorna `{ por, ...contexto, count, votacoes }`, cada votação com `codigo`, `data`, `comissao`, `reuniao`, `materia`, `descricao`, totais publicados pela fonte (`totalSim`/`totalNao`/`totalAbstencao`; contados dos votos, com `placarComputado: true`, só quando a fonte não os traz) e `votos` (senador, partido, voto). Sem paginação. Períodos amplos podem estourar o tempo-limite da consulta (erro de timeout): prefira janelas de até 3 meses e divida períodos maiores em chamadas sucessivas. " +
         "Obtenha siglas via `senado_listar_comissoes`, `codigoSenador` via `senado_listar_senadores`; para votações no plenário use `senado_votos_materia`. Atenção: o `codigo` de cada votação de comissão pertence a um espaço de numeração próprio e NÃO é válido em `senado_obter_votacao` (que é exclusivo de plenário) — podem coincidir numericamente, mas apontam para votações diferentes.", {
         por: z.enum(["comissao", "senador", "materia"]).optional().default("comissao").describe("Eixo da consulta: comissao, senador ou materia"),
         siglaComissao: z.string().min(2).optional().describe("Sigla da comissão (obrigatório quando por=comissao; ex: CCJ, CAE)"),
@@ -97,7 +122,7 @@ export function registerVotacaoComissaoTools(server, baseUrl) {
                         ? `${params.dataInicio}/${params.dataFim}` : undefined,
                     retrieved_at: fetchedAt,
                 });
-                return resultWithProvenance({ por, codigoSenador: params.codigoSenador, count: votacoes.length, votacoes }, prov);
+                return resultWithProvenance({ por, codigoSenador: params.codigoSenador, count: votacoes.length, votacoes }, provenanceDaVotacaoComissao(prov, votacoes));
             }
             if (por === "materia") {
                 if (!params.sigla || !params.numero || !params.ano) {
@@ -117,7 +142,7 @@ export function registerVotacaoComissaoTools(server, baseUrl) {
                     reference_period: String(params.ano),
                     retrieved_at: fetchedAt,
                 });
-                return resultWithProvenance({ por, materia: `${sigla} ${params.numero}/${params.ano}`, count: votacoes.length, votacoes }, prov);
+                return resultWithProvenance({ por, materia: `${sigla} ${params.numero}/${params.ano}`, count: votacoes.length, votacoes }, provenanceDaVotacaoComissao(prov, votacoes));
             }
             // por === "comissao" (padrão)
             if (!params.siglaComissao)
@@ -136,7 +161,7 @@ export function registerVotacaoComissaoTools(server, baseUrl) {
                     ? `${params.dataInicio}/${params.dataFim}` : undefined,
                 retrieved_at: fetchedAt,
             });
-            return resultWithProvenance({ por, siglaComissao: sigla, count: votacoes.length, votacoes }, prov);
+            return resultWithProvenance({ por, siglaComissao: sigla, count: votacoes.length, votacoes }, provenanceDaVotacaoComissao(prov, votacoes));
         }
         catch (e) {
             return errorFrom(e, "Erro ao obter votações em comissões");

package/dist/tools/votacoes.js

@@ -11,7 +11,7 @@ import { cachedFetchWithMeta } from "../cache/manager.js";
 import { upstreamFetch } from "../throttle/upstream.js";
 import { toolError, errorFrom, buildParams, ensureArray } from "../utils/validation.js";
 import { computarPlacar } from "../utils/placar.js";
-import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
+import { NOTA_DERIVACAO_PLACAR, derivadoSe, provenanceFor, resultWithProvenance } from "../utils/provenance.js";
 import { CACHE_ON_DEMAND } from "../types.js";
 /** Convert YYYYMMDD → YYYY-MM-DD (required by /votacao endpoint). */
 export function toISODate(yyyymmdd) {
@@ -42,6 +42,12 @@ export function expandirResultado(code) {
     const raw = String(code).trim();
     return { resultado: RESULTADO_VOTACAO[raw.toUpperCase()] ?? raw, resultadoCodigo: raw };
 }
+/**
+ * Provenance of a plenary vote response (contract v1.3): `derived` only when at least one item's
+ * tally was counted from the nominal votes (`placarComputado`); totals the source publishes are
+ * copied and do not mark the block.
+ */
+export const provenanceDaVotacao = (prov, votacoes) => derivadoSe(prov, votacoes.some((v) => v.placarComputado === true), NOTA_DERIVACAO_PLACAR);
 /** Parse a single vote item from the /votacao endpoint (flat camelCase). */
 export function parseVotacaoItem(v, includeVotos = false) {
     const votosRaw = Array.isArray(v.votos) ? v.votos : [];
@@ -138,8 +144,8 @@ export function registerVotacoesTools(server, baseUrl) {
                     retrieved_at: fetchedAt,
                 });
                 if (votacoes.length === 1)
-                    return resultWithProvenance(votacoes[0], prov);
-                return resultWithProvenance({ codigoSessao: codigo, count: votacoes.length, votacoes }, prov);
+                    return resultWithProvenance(votacoes[0], provenanceDaVotacao(prov, votacoes));
+                return resultWithProvenance({ codigoSessao: codigo, count: votacoes.length, votacoes }, provenanceDaVotacao(prov, votacoes));
             }
             // 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
@@ -152,11 +158,11 @@ export function registerVotacoesTools(server, baseUrl) {
             const achado = acharPorCodigoVotacao(cru, codigo);
             if (achado) {
                 const votacao = parseVotacaoItem(achado, true);
-                return resultWithProvenance(votacao, provenanceFor("SENADO_LEGIS", baseUrl, "/votacao", {
+                return resultWithProvenance(votacao, provenanceDaVotacao(provenanceFor("SENADO_LEGIS", baseUrl, "/votacao", {
                     dataset_id: `${CAMPO_VOTACAO}=${codigo}`,
                     reference_period: votacao.data || undefined,
                     retrieved_at: fetchedAtJanela,
-                }));
+                }), [votacao]));
             }
             // PASSO 3 — não está em nenhum dos dois espaços: ausência TIPADA.
             const ondeProcurou = params.ano
@@ -187,7 +193,7 @@ export function registerVotacoesTools(server, baseUrl) {
                 reference_period: votacoes[0]?.data || undefined,
                 retrieved_at: fetchedAt,
             });
-            return resultWithProvenance({ codigoMateria: params.codigoMateria, count: votacoes.length, votacoes }, prov);
+            return resultWithProvenance({ codigoMateria: params.codigoMateria, count: votacoes.length, votacoes }, provenanceDaVotacao(prov, votacoes));
         }
         catch (e) {
             return errorFrom(e, "Erro ao obter votações da matéria");
@@ -235,7 +241,7 @@ export function registerVotacoesTools(server, baseUrl) {
                 reference_period: di && df ? `${di}/${df}` : di || df || undefined,
                 retrieved_at: fetchedAt,
             });
-            return resultWithProvenance({ count: votacoes.length, votacoes }, prov);
+            return resultWithProvenance({ count: votacoes.length, votacoes }, provenanceDaVotacao(prov, votacoes));
         }
         catch (e) {
             return errorFrom(e, "Erro na busca de votações");

package/dist/utils/provenance.js

@@ -277,17 +277,49 @@ export function withFieldSources(prov, fieldSources) {
  */
 export const NOTA_DERIVACAO_ESTATISTICAS = "Estatísticas (distribuição, agregados e rankings) computadas pelo servidor a partir dos registros brutos retornados pela fonte; os valores individuais permanecem os originais do Senado Federal.";
 /**
- * Marca o bloco como derivado (contrato v1.3): `derived: true` + a nota fixa dos modos
- * `estatisticas`. Aplique por último, sobre o bloco já completo (inclusive o de
- * `withFieldSources`); o envelope é re-validado inteiro no contrato (build).
+ * Notas fixas dos demais cálculos do servidor (contrato v1.3, 3.19.0). Uma por TIPO de
+ * cálculo, não por tool: o leitor precisa saber o que foi calculado, não onde.
  */
-export function derivadoDeEstatisticas(prov) {
+/** Somas, contagens e médias por grupo (modos agregados, `valorTotal`, contagens por unidade/partido/UF). */
+export const NOTA_DERIVACAO_SOMAS = "Totais, contagens e médias por grupo calculados pelo servidor a partir dos registros da fonte; os valores individuais permanecem os originais do Senado Federal.";
+/** `bruto` das remunerações: soma dos sete componentes da folha. */
+export const NOTA_DERIVACAO_BRUTO = "A remuneração bruta é a soma, feita pelo servidor, dos sete componentes publicados pela fonte, que permanecem os originais.";
+/** Servidores sob uma unidade: classificação de cada lotação no organograma, feita pelo servidor. */
+export const NOTA_DERIVACAO_SUBORDINADAS = "Servidores atribuídos a cada unidade e contados pelo servidor, cruzando a lotação de cada um com o organograma publicado; o total é um piso (lotações não reconhecidas ficam de fora).";
+/** Placar de votação do plenário contado dos votos nominais (votação aberta sem totais na fonte). */
+export const NOTA_DERIVACAO_PLACAR = "Totais de votos contados pelo servidor a partir dos votos nominais, porque a fonte não publica o placar desta votação.";
+/** Placar de votação de comissão contado dos votos, quando a fonte não traz os totais. */
+export const NOTA_DERIVACAO_PLACAR_COMISSAO = "Totais de votos de pelo menos uma votação contados pelo servidor a partir dos votos de cada parlamentar, porque a fonte não publicou o placar dela.";
+/** Percentuais (e o total, quando ausente) das consultas públicas do e-Cidadania. */
+export const NOTA_DERIVACAO_PERCENTUAIS = "Percentuais de sim e não, e o total de votos quando a fonte não o publica, calculados pelo servidor a partir dos votos da fonte.";
+/** Polarização, consenso e ordem por participação no e-Cidadania. */
+export const NOTA_DERIVACAO_RANKING_ECIDADANIA = "Polarização, consenso e ordem por participação calculados pelo servidor a partir dos votos e apoios publicados pela fonte.";
+/** Data de criação estimada das ideias legislativas. */
+export const NOTA_DERIVACAO_DATA_ESTIMADA = "A data de criação é estimada pelo servidor (fim do prazo de apoio menos 120 dias); a fonte não a publica.";
+/** Legislatura sem número na fonte: o próprio número é o padrão do servidor. */
+export const NOTA_DERIVACAO_LEGISLATURA_PADRAO = "A fonte não informou a legislatura: o servidor assume a 57ª (2023–2027) e calcula o período e as datas.";
+/** Período e datas da legislatura derivados do número dela. */
+export const NOTA_DERIVACAO_LEGISLATURA = "Período e datas da legislatura calculados pelo servidor a partir do número publicado pela fonte (mandatos de quatro anos).";
+/**
+ * Marca o bloco como derivado (contrato v1.3): `derived: true` + a nota dada. Aplique por
+ * último, sobre o bloco já completo (inclusive o de `withFieldSources`); o envelope é
+ * re-validado inteiro no contrato (build).
+ */
+export function derivado(prov, nota) {
     return provenanceContext.build({
         ...prov,
         derived: true,
-        derivation_note: NOTA_DERIVACAO_ESTATISTICAS,
+        derivation_note: nota,
     });
 }
+/** `derivado` só quando `calculou`; senão o bloco volta intacto (sem `derived`). */
+export function derivadoSe(prov, calculou, nota) {
+    return calculou ? derivado(prov, nota) : prov;
+}
+/** `derivado` com a nota dos modos `estatisticas`. */
+export function derivadoDeEstatisticas(prov) {
+    return derivado(prov, NOTA_DERIVACAO_ESTATISTICAS);
+}
 /** Rodapé de texto do contrato: fonte · url · vintage · extração, licença e aviso ao leitor. */
 export const provenanceFooter = (p) => provenanceContext.footer(p);
 /**

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.18.5";
+export const VERSION = "3.19.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.18.5",
+  "version": "3.19.0",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "keywords": [
     "mcp",