senado-br-mcp 3.16.0 → 3.18.0

package/README.md

@@ -532,7 +532,7 @@ This caching happens at the **tool level** (inside each tool's callback), not at
 
 ## Provenance
 
-**Every tool** attaches a **provenance envelope** so a result is traceable back to its official source — provenance is treated as a first-class part of the answer, not an optional extra (the audience is journalists and political-science researchers, for whom an un-sourced figure is unusable). Since **v3.5.0** the envelope implements the portfolio-wide **provenance contract v1.0** ([`@sbissoli/mcp-provenance`](https://www.npmjs.com/package/@sbissoli/mcp-provenance)): the server builds and validates a full canonical model per response, and emits its **`concise` projection** — a fixed 6-key block with explicit `null` for unknown fields. The block lives in `structuredContent.provenance` (parseable by clients; note the advertised per-tool output schema is permissive, so contract validation happens server-side at build time, in the package) and is mirrored as a compact source footer in the text content for clients that only render text — the data JSON itself is **not** duplicated with the envelope, to keep the per-response token cost low.
+**Every tool** attaches a **provenance envelope** so a result is traceable back to its official source — provenance is treated as a first-class part of the answer, not an optional extra (the audience is journalists and political-science researchers, for whom an un-sourced figure is unusable). The envelope implements the portfolio-wide **provenance contract** ([`@sbissoli/mcp-provenance`](https://www.npmjs.com/package/@sbissoli/mcp-provenance)): the server builds and validates a full canonical model per response, and emits its **`concise` projection** — a fixed-order block with explicit `null` for unknown fields; responses that merge several upstream reads also list each part with its own extraction instant (`field_sources`), and the block's `retrieved_at` is then the oldest of them. The block lives in `structuredContent.provenance` (parseable by clients; note the advertised per-tool output schema is permissive, so contract validation happens server-side at build time, in the package) and is mirrored as a compact source footer in the text content for clients that only render text — the data JSON itself is **not** duplicated with the envelope, to keep the per-response token cost low.
 
 Coverage spans all four upstream sources, each with its own `source`/`citation`/`license` (in `src/utils/provenance.ts`):
 
@@ -581,7 +581,7 @@ Each release ships one NDJSON resource per entity (one `HarmonizedRecord` per li
 | Resource (`*.ndjson`) | Grain | Key variables | Source(s) |
 |---|---|---|---|
 | `consultas` | 1 public consultation (matéria) | `materia`, `ementa`, `votosSim`/`votosNao`/`totalVotos`, `percentual*`, **`autoria`ⁿ**, **`relator`ⁿ**, `status`, `url`, `firstSeenAt` | `pesquisamateria` listing + **detail** (`visualizacaomateria`)ⁿ + `/processo?tramitando=S` for status |
-| `ideias` | 1 legislative idea (~113.7k) | `titulo`, `apoios`, `status`, **`dataPublicacao`ⁿ**, **`autorUf`ⁿ**, **`descricao`ⁿ**, **`plConvertido`ⁿ**, `url`, `firstSeenAt` | `pesquisaideia` listing + **detail** (`visualizacaoideia`) via a resumable backfillⁿ |
+| `ideias` | 1 legislative idea (~113.7k) | `titulo`, `apoios`, `status`, **`dataPublicacao`ⁿ** (the *support deadline* — the only date the portal publishes; creation ≈ deadline − 120 days, see the dictionary), **`autorUf`ⁿ**, **`descricao`ⁿ**, **`plConvertido`ⁿ**, `url`, `firstSeenAt` | `pesquisaideia` listing + **detail** (`visualizacaoideia`) via a resumable backfillⁿ |
 | `eventos` | 1 interactive event (audiência) | `titulo`, **`data`ᶜ**, **`hora`ᶜ**, `comissao`, **`comissaoNomeCompleto`ⁿ**, **`local`ⁿ**, **`descricao`ⁿ**, **`pauta`ⁿ**, **`convidados`ⁿ**, **`videoUrl`ⁿ**, **`comentarios`ᶜ**, `status`, `url`, `firstSeenAt` | `principalaudiencia` listing + **detail** (`visualizacaoaudiencia`)ⁿ + **AJAX comment fragment**ᶜ |
 | **`eventos_comentarios`ⁿ** | 1 comment (comment-level) | `eventoId`, `comentarioId`, `uf`, `texto`, `data`, `hora`, `momentoVideoUrl`, `convidadoAssociado` | AJAX fragment `ajaxcolecaocomentarioaudiencia?audienciaId=` |
 | `consultas_votos` | 1 matéria (historical acervo) | `materia`, `ementa`, `autoria`, `votosSim`/`votosNao`/`totalVotos`, `votosPorUf`, `status`, `url`, `referencePeriod` | Arquimedes CSV `Proposições-com-votos.csv` (re-ingested weekly) |

package/dist/dataset/schema.js

@@ -191,11 +191,11 @@ const ideiasSchema = {
         {
             name: "dataPublicacao",
             type: "date",
-            description: "Data limite para atingir os 20.000 apoios (única âncora temporal upstream da ideia).",
+            description: "Data limite para atingir os 20.000 apoios (única âncora temporal upstream da ideia). NÃO é a data de criação: o nome é histórico, mantido pela compatibilidade do esquema.",
             sourceEndpoint: EP_IDEIAS_DETALHE,
-            sourceField: "página de detalhe: bloco \"Data limite\" (DD/MM/AAAA)",
-            operationalization: "extractDate sobre a data-limite exibida no detalhe (visualizacaoideia) → ISO YYYY-MM-DD; lido no crawl de detalhe. Reaberto na v2 (era null por design na v1).",
-            caveat: "Detail-only (v2): null nas ideias ainda não enriquecidas pelo backfill de detalhe (censura à esquerda residual nesses campos até o backfill completar).",
+            sourceField: "página de detalhe: bloco \"Data limite para receber 20.000 apoios\" (DD/MM/AAAA)",
+            operationalization: "extractDate sobre a data-limite exibida no detalhe (visualizacaoideia) → ISO YYYY-MM-DD; lido no crawl de detalhe. Reaberto na v2 (era null por design na v1). Data provável de criação = esta data − 120 dias (regra dos 4 meses do portal; medida exata em 4 ideias convertidas de 2017-2020 contra a base de Pereira, UFPE 2024) — derivação do leitor, não variável do dataset.",
+            caveat: "Em ideia aberta esta data está no futuro (é o fim do prazo de apoios). Detail-only (v2): null nas ideias ainda não enriquecidas pelo backfill de detalhe (censura à esquerda residual nesses campos até o backfill completar).",
         },
         {
             name: "autorUf",

package/dist/scraper/ecidadania.js

@@ -253,6 +253,44 @@ export async function obterConsultaInternal(id) {
         linkMateria: null,
     };
 }
+// ── Ideias ─────────────────────────────────────────────────────────────
+/**
+ * Prazo de apoios de uma ideia, em dias. O portal diz que "as ideias ficam abertas por 4 meses"
+ * (`/comofuncionaideia`) e publica UMA data só, a "Data limite para receber 20.000 apoios" — é ela
+ * que o campo `dataPublicacao` guarda (nome histórico; ver `AVISO_DATAS_IDEIA`). Medido em
+ * 09/10/2026 contra a data de proposição de 4 ideias convertidas (base de Pereira, UFPE 2024,
+ * github.com/theus0307/dissertacao): a data limite é SEMPRE a proposição + 120 dias exatos —
+ * SUG 49/2017 12/09/2017 → 10/01/2018; SUG 43/2019 14/10/2019 → 11/02/2020; SUG 49/2019
+ * 31/07/2019 → 28/11/2019; SUG 21/2020 02/06/2020 → 30/09/2020. "4 meses" de calendário erraria
+ * em 2 a 3 dias em todas.
+ */
+export const IDEIA_PRAZO_APOIOS_DIAS = 120;
+/**
+ * Aviso que acompanha as datas de ideia na saída das tools. Vai JUNTO do dado, não só na descrição
+ * da tool: a descrição é lida uma vez, o dado é lido a cada resposta, e a data limite de uma ideia
+ * aberta cai no futuro — sem o aviso o leitor conclui que o servidor errou.
+ */
+export const AVISO_DATAS_IDEIA = "dataPublicacao é a data limite para receber os 20.000 apoios, a única data que o portal publica (o nome do campo é histórico); " +
+    "por isso cai no futuro em ideia aberta. dataCriacaoEstimada = data limite menos 120 dias, calculada pelo servidor " +
+    "(regra dos 4 meses do portal, medida em 4 ideias de 2017-2020): é estimativa, não dado da fonte.";
+/**
+ * Data provável de criação da ideia: data limite (ISO) − `IDEIA_PRAZO_APOIOS_DIAS`. Aritmética em UTC
+ * sobre o dia civil (sem fuso, sem horário de verão). Data ausente ou inválida → null, nunca uma data
+ * inventada (o `Date` "corrige" 31/02 para 03/03; aqui isso é rejeitado).
+ */
+export function estimarCriacaoIdeia(dataLimite) {
+    if (!dataLimite)
+        return null;
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dataLimite);
+    if (!m)
+        return null;
+    const [ano, mes, dia] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const t = Date.UTC(ano, mes - 1, dia);
+    const d = new Date(t);
+    if (Number.isNaN(t) || d.getUTCFullYear() !== ano || d.getUTCMonth() !== mes - 1 || d.getUTCDate() !== dia)
+        return null;
+    return new Date(t - IDEIA_PRAZO_APOIOS_DIAS * 86_400_000).toISOString().slice(0, 10);
+}
 /**
  * Canonical `IdeiaResumo` builder — single source of the object's field order, so the JSON payload
  * (and `contentHash`) is byte-identical across the writers into `ecidadania_current`: the 2h highlight

package/dist/tools/ecidadania.js

@@ -16,9 +16,9 @@ import { provenanceEcidadania, provenanceArquimedesVotos, resultWithProvenance }
 import { tagUntrustedFields, tagUntrustedList, neutralizeUntrustedText, sanitizeScrapedText } from "../utils/untrusted.js";
 import { CACHE_ON_DEMAND } from "../types.js";
 import { resolveList, writeDetalheThrough } from "../scraper/store.js";
-import { ECIDADANIA_BASE, parseBrNum, extractId, normalizeEcidadaniaUrl, stripHtml, extractDate, extractTime, buildConsultaResumo, listarConsultasInternal, obterConsultaInternal, listarIdeiasInternal, obterIdeiaInternal, listarEventosInternal, obterEventoInternal, } from "../scraper/ecidadania.js";
+import { ECIDADANIA_BASE, parseBrNum, extractId, normalizeEcidadaniaUrl, stripHtml, extractDate, extractTime, buildConsultaResumo, listarConsultasInternal, obterConsultaInternal, listarIdeiasInternal, obterIdeiaInternal, listarEventosInternal, obterEventoInternal, estimarCriacaoIdeia, AVISO_DATAS_IDEIA, IDEIA_PRAZO_APOIOS_DIAS, } from "../scraper/ecidadania.js";
 // Re-export the scraper's pure/IO helpers so existing unit tests keep importing them from here.
-export { ECIDADANIA_BASE, parseBrNum, extractId, normalizeEcidadaniaUrl, stripHtml, extractDate, extractTime, buildConsultaResumo, listarConsultasInternal, obterConsultaInternal, listarIdeiasInternal, obterIdeiaInternal, listarEventosInternal, obterEventoInternal, };
+export { estimarCriacaoIdeia, AVISO_DATAS_IDEIA, IDEIA_PRAZO_APOIOS_DIAS, ECIDADANIA_BASE, parseBrNum, extractId, normalizeEcidadaniaUrl, stripHtml, extractDate, extractTime, buildConsultaResumo, listarConsultasInternal, obterConsultaInternal, listarIdeiasInternal, obterIdeiaInternal, listarEventosInternal, obterEventoInternal, };
 /** Format an integer with pt-BR thousands separators ("253804" → "253.804").
  *  Avoids toLocaleString, whose Intl data is not guaranteed on Workers (OBS-12). */
 export function formatIntBR(n) {
@@ -163,7 +163,7 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
         }
     });
     // G5. senado_ecidadania_listar_ideias
-    server.tool("senado_ecidadania_listar_ideias", "Lista ideias legislativas propostas por cidadãos no e-Cidadania — **conjunto completo** (corpus persistido em D1; ideias em andamento atualizadas diariamente; ~118 mil ideias, incluindo encerradas e convertidas em proposição). Retorna `{ count, ideias }`, cada ideia com `id`, `titulo`, `apoios`, `status` (`aberta`/`encerrada`/`convertida`/`removida` — `removida` = retirada do portal, que não a publica mais; o corpus guarda o último estado conhecido) e `url` (`autor` e `dataPublicacao` só aparecem no detalhe, vêm `null` aqui). Aceita filtro por `status` e `limite` (padrão 20). Para um ranking das mais apoiadas, ordene por apoios (`ordenarPor: \"apoios\"`, `ordem: \"desc\"`). Para o detalhe completo de uma ideia (texto, autor, se virou projeto de lei) chame `senado_ecidadania_obter_ideia` com o `id`.", {
+    server.tool("senado_ecidadania_listar_ideias", "Lista ideias legislativas propostas por cidadãos no e-Cidadania — **conjunto completo** (corpus persistido em D1; ideias em andamento atualizadas diariamente; ~118 mil ideias, incluindo encerradas e convertidas em proposição). Retorna `{ count, ideias, avisoDatas }`, cada ideia com `id`, `titulo`, `apoios`, `status` (`aberta`/`encerrada`/`convertida`/`removida` — `removida` = retirada do portal, que não a publica mais; o corpus guarda o último estado conhecido), `url` e os campos lidos do detalhe quando o backfill já passou por ela (`dataPublicacao`, `autorUf`, `descricao`, `plConvertido`; `null` até lá). **Datas:** `dataPublicacao` é a DATA LIMITE para receber os 20.000 apoios — a única data que o portal publica; o nome do campo é histórico — e por isso cai no futuro em ideia aberta; `dataCriacaoEstimada` (= data limite − 120 dias, a regra dos 4 meses do portal) é calculada pelo servidor e é estimativa, não dado da fonte; `avisoDatas` repete isso na resposta. Aceita filtro por `status` e `limite` (padrão 20). Para um ranking das mais apoiadas, ordene por apoios (`ordenarPor: \"apoios\"`, `ordem: \"desc\"`). Para o detalhe completo de uma ideia (texto, autor, se virou projeto de lei) chame `senado_ecidadania_obter_ideia` com o `id`.", {
         status: z.enum(["aberta", "encerrada", "convertida", "removida", "todas"]).optional().describe("Filtrar por status (`removida` = retirada do portal)"),
         ordenarPor: z.enum(["apoios", "data", "comentarios"]).optional().describe("Campo para ordenação (apoios é o disponível no corpus; data/comentarios só no detalhe)"),
         ordem: z.enum(["asc", "desc"]).optional().describe("Ordem de ordenação"),
@@ -181,19 +181,34 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
             const limite = params.limite ?? 20;
             const offset = ((params.pagina ?? 1) - 1) * limite;
             arr = arr.slice(offset, offset + limite);
-            return resultWithProvenance({ count: arr.length, ideias: tagUntrustedList("ideias", arr), meta }, provLista("/principalideia", "ideias", meta));
+            // Derivado na SAÍDA, nunca no corpus: `IdeiaResumo` é o payload persistido (hash estável).
+            const ideias = arr.map((i) => ({ ...i, dataCriacaoEstimada: estimarCriacaoIdeia(i.dataPublicacao) }));
+            return resultWithProvenance({
+                count: ideias.length,
+                ideias: tagUntrustedList("ideias", ideias),
+                avisoDatas: AVISO_DATAS_IDEIA,
+                meta,
+            }, provLista("/principalideia", "ideias", meta));
         }
         catch (e) {
             return ecidadaniaError(e);
         }
     });
     // G6. senado_ecidadania_obter_ideia
-    server.tool("senado_ecidadania_obter_ideia", "Obtém o detalhe de uma ideia legislativa do e-Cidadania. Retorna um objeto com `id`, `titulo`, `descricao` (texto completo, truncado em ~2000 caracteres), `apoios`, `dataPublicacao`, `status`, `autor`, `url` e `plConvertido` (sigla/número quando virou projeto de lei). O campo `comentarios` vem `null`: a página de ideia não possui recurso de comentários. Obtenha o `id` antes via `senado_ecidadania_listar_ideias`.", { id: z.number().int().positive().describe("ID da ideia legislativa") }, async (params) => {
+    server.tool("senado_ecidadania_obter_ideia", "Obtém o detalhe de uma ideia legislativa do e-Cidadania. Retorna um objeto com `id`, `titulo`, `descricao` (texto completo, truncado em ~2000 caracteres), `apoios`, `dataPublicacao`, `dataCriacaoEstimada`, `avisoDatas`, `status`, `autor`, `url` e `plConvertido` (sigla/número quando virou projeto de lei). **Datas:** `dataPublicacao` é a DATA LIMITE para receber os 20.000 apoios — a única data que o portal publica; o nome do campo é histórico — e por isso cai no futuro em ideia aberta; `dataCriacaoEstimada` (= data limite − 120 dias, a regra dos 4 meses do portal) é calculada pelo servidor e é estimativa, não dado da fonte. O campo `comentarios` vem `null`: a página de ideia não possui recurso de comentários. Obtenha o `id` antes via `senado_ecidadania_listar_ideias`.", { id: z.number().int().positive().describe("ID da ideia legislativa") }, async (params) => {
         try {
             const { value: r, fetchedAt } = await cachedFetchWithMeta("ecidadania_ideia", { id: params.id }, CACHE_ON_DEMAND, () => obterIdeiaInternal(params.id));
             writeDetalheThrough(db, ctx, "ideias", params.id, r);
             // OBS-9: idea pages have no comments resource — serve null instead of a spurious 0.
-            const detalhe = { ...r, comentarios: null };
+            // Datas: `dataCriacaoEstimada` e `avisoDatas` entram SÓ na resposta (não no write-through acima,
+            // que guarda o que a página diz).
+            const ideia = r;
+            const detalhe = {
+                ...r,
+                dataCriacaoEstimada: estimarCriacaoIdeia(ideia.dataPublicacao),
+                comentarios: null,
+                avisoDatas: AVISO_DATAS_IDEIA,
+            };
             return resultWithProvenance(tagUntrustedFields("ideias", detalhe), provDetalhe(r, `/visualizacaoideia?id=${params.id}`, `ideia=${params.id}`, fetchedAt));
         }
         catch (e) {

package/dist/tools/estrutura.js

@@ -31,6 +31,7 @@ export function provenanceEstrutura() {
         dataset_id: "estrutura-organizacional",
         reference_period: ESTRUTURA_VINTAGE.slice(0, 10),
         retrieved_at: ESTRUTURA_VINTAGE,
+        revision: SOURCES.SENADO_INSTITUCIONAL.revision,
     });
 }
 /** Forma pública de um órgão (nunca expõe o código interno). */

package/dist/tools/materias.js

@@ -125,6 +125,44 @@ export function parseDocumentoProcesso(d) {
  * Resolve codigoMateria → processo summary item via /processo?codigoMateria=.
  * Devolve também o `fetchedAt` do cache p/ a granularidade por-campo (o resumo dá a `ementa`).
  */
+/**
+ * Proveniência de `senado_obter_materia` secao=detalhe, que funde 3 endpoints: o detalhe
+ * (`/processo/{id}`, fonte de topo), a `ementa` do resumo (`/processo`) e o `relator` da
+ * relatoria (`/processo/relatoria`, só quando há relator), cada um com o seu instante real.
+ *
+ * Os três são lidos em momentos (e de entradas de cache) distintos, então o detalhe
+ * também entra como sub-fonte: o `retrieved_at` do topo é derivado pelo adaptador como o
+ * MAIS ANTIGO das três (contrato §3) e, sem este item, o instante do detalhe sumiria do
+ * bloco quando o resumo fosse mais velho. Antes da 3.17.0 o topo era o fetch do detalhe,
+ * feito DEPOIS das sub-fontes — com a v1.2 ligada, a lib lançaria e a tool cairia.
+ */
+export function provenanceMateriaDetalhe(baseUrl, a) {
+    const base = baseUrl.replace(/\/$/, "");
+    const dataset_id = `codigoMateria=${a.codigoMateria}`;
+    const fieldSources = [
+        {
+            fields: Object.keys(a.detalhe),
+            source_url: `${base}/processo/${a.idProcesso}`,
+            dataset_id,
+            retrieved_at: a.detalheFetchedAt,
+        },
+        { fields: ["ementa"], source_url: `${base}/processo`, dataset_id, retrieved_at: a.resumoFetchedAt },
+    ];
+    if (a.relatoriaFetchedAt !== undefined) {
+        fieldSources.push({
+            fields: ["relator"],
+            source_url: `${base}/processo/relatoria`,
+            dataset_id,
+            retrieved_at: a.relatoriaFetchedAt,
+        });
+    }
+    return provenanceFor("SENADO_LEGIS", baseUrl, `/processo/${a.idProcesso}`, {
+        dataset_id,
+        reference_period: a.detalhe.dataApresentacao || (a.detalhe.ano ? String(a.detalhe.ano) : undefined),
+        retrieved_at: a.detalheFetchedAt,
+        field_sources: fieldSources,
+    });
+}
 async function resolveProcesso(codigoMateria, baseUrl) {
     const { value: response, fetchedAt } = await cachedFetchWithMeta("_processo_por_materia", { codigoMateria }, CACHE_ON_DEMAND, () => upstreamFetch("/processo", { codigoMateria: String(codigoMateria) }, baseUrl));
     const item = ensureArray(response)[0];
@@ -267,7 +305,8 @@ export function registerMateriasTools(server, baseUrl) {
             // secao === "detalhe" (padrão) — funde 3 endpoints numa só resposta, então a
             // proveniência ganha granularidade por-campo (field_sources): a fonte de topo é o
             // detalhe (/processo/{id}); a `ementa` vem do resumo (/processo) e o `relator` da
-            // relatoria (/processo/relatoria), cada um com o seu retrieved_at real.
+            // relatoria (/processo/relatoria), cada um com o seu retrieved_at real; o do topo é
+            // o mais antigo dos três (ver `provenanceMateriaDetalhe`).
             const [resumoRes, relatoriasRes] = await Promise.all([
                 resolveProcesso(params.codigoMateria, baseUrl),
                 cachedFetchWithMeta("_processo_relatoria", { codigoMateria: params.codigoMateria }, CACHE_ON_DEMAND, () => upstreamFetch("/processo/relatoria", { codigoMateria: String(params.codigoMateria) }, baseUrl)).catch(() => null),
@@ -276,24 +315,13 @@ export function registerMateriasTools(server, baseUrl) {
             const { value: detalheRes, fetchedAt } = await cachedFetchWithMeta("senado_obter_materia", { idProcesso: resumo.id }, CACHE_ON_DEMAND, () => upstreamFetch(`/processo/${resumo.id}`, {}, baseUrl));
             const detalhe = parseProcessoDetalhe(detalheRes);
             const relator = pickRelatorAtual(ensureArray(relatoriasRes?.value));
-            const base = baseUrl.replace(/\/$/, "");
-            const dataset_id = `codigoMateria=${params.codigoMateria}`;
-            const fieldSources = [
-                { fields: ["ementa"], source_url: `${base}/processo`, dataset_id, retrieved_at: resumoRes.fetchedAt },
-            ];
-            if (relator) {
-                fieldSources.push({
-                    fields: ["relator"],
-                    source_url: `${base}/processo/relatoria`,
-                    dataset_id,
-                    retrieved_at: relatoriasRes?.fetchedAt,
-                });
-            }
-            const prov = provenanceFor("SENADO_LEGIS", baseUrl, `/processo/${resumo.id}`, {
-                dataset_id,
-                reference_period: detalhe.dataApresentacao || (detalhe.ano ? String(detalhe.ano) : undefined),
-                retrieved_at: fetchedAt,
-                field_sources: fieldSources,
+            const prov = provenanceMateriaDetalhe(baseUrl, {
+                codigoMateria: params.codigoMateria,
+                idProcesso: resumo.id,
+                detalhe,
+                detalheFetchedAt: fetchedAt,
+                resumoFetchedAt: resumoRes.fetchedAt,
+                relatoriaFetchedAt: relator ? relatoriasRes?.fetchedAt : undefined,
             });
             return resultWithProvenance({
                 ...detalhe,

package/dist/tools/servidores.js

@@ -331,6 +331,36 @@ export function particionarPorUnidade(lista, indice, codUnidade) {
         afastadosOuEmTransito,
     };
 }
+/**
+ * Proveniência de `senado_servidores` com `subordinadasA`: a classificação cruza a folha
+ * (fonte administrativa, buscada/cacheada nesta chamada — `prov`) com o organograma (fonte
+ * institucional, snapshot extraído do portal em `ESTRUTURA_VINTAGE` e embutido no bundle).
+ *
+ * O `retrieved_at` do snapshot é o instante REAL da extração no portal (o crawler o grava
+ * em `extraidoEm`), não uma data de build — então fica: zerá-lo para `null` diria "não sei
+ * quando foi extraído", o que é falso, e trocá-lo pelo instante da folha diria que o
+ * organograma foi lido agora, o que também é. Com ele, o topo passa a ser o mais antigo
+ * das duas (derivado pelo adaptador, contrato §3), e a folha entra como sub-fonte própria
+ * para que o seu instante não suma do bloco. Antes da 3.17.0 o topo era o da folha, mais
+ * novo que o snapshot — com a v1.2 ligada, a lib lançaria e a tool cairia.
+ */
+export function provenanceServidoresSubordinadas(prov, situacao) {
+    return withFieldSources(prov, [
+        {
+            fields: ["servidores", "total", "count", "naoClassificados", "afastadosOuEmTransito"],
+            source_url: prov.source_url,
+            dataset_id: `servidores; situacao=${situacao}`,
+            retrieved_at: prov.retrieved_at,
+        },
+        {
+            fields: ["subordinadasA", "total", "naoClassificados"],
+            source_url: provenanceEstrutura().source_url,
+            dataset_id: "estrutura-organizacional",
+            reference_period: ESTRUTURA_VINTAGE.slice(0, 10),
+            retrieved_at: ESTRUTURA_VINTAGE,
+        },
+    ]);
+}
 export function registerServidoresTools(server, admBaseUrl) {
     // P1. senado_servidores
     server.tool("senado_servidores", "Lista servidores do Senado por `situacao` (ativos, efetivos, comissionados ou inativos), com filtros opcionais por `nome`, `lotacao` e `cargo`. Retorna `{ situacao, count, total, servidores[] }`, cada item com `nome`, `vinculo`, `situacao`, `cargo`, `funcao`, `lotacao`, `anoAdmissao` etc. Aplica `limite` (padrão 50, máx 500) e inclui `aviso` quando há truncamento — refine os filtros. Também conta e lista TODOS os servidores de TODA a estrutura subordinada a uma diretoria/secretaria (não só a lotação direta), cruzando a lotação de cada servidor com o organograma até o nível de serviço: informe a unidade (sigla ou nome, ex.: 'DGER') em `subordinadasA` — use isso para 'quantas pessoas estão sob a Diretoria-Geral', pois filtrar `lotacao` pela sigla-mãe retorna 0 (os servidores ficam em serviços/núcleos subordinados). Nesse modo o retorno traz a unidade resolvida, o total (um piso), os servidores, as unidades não reconhecidas no organograma (`naoClassificados`, com nota explicativa) e os afastados/em trânsito (`afastadosOuEmTransito`); ao responder, verbalize esses conceitos em português corrente — não cite nomes de parâmetros ou campos. Para o organograma em si use `senado_estrutura_organizacional`; para remuneração use `senado_remuneracoes_servidores`.", {
@@ -368,15 +398,7 @@ export function registerServidoresTools(server, admBaseUrl) {
                     return toolError(`Unidade '${params.subordinadasA}' não encontrada na estrutura organizacional.${dica}`, "nao_encontrado");
                 }
                 const { sob, naoClassificados, afastadosOuEmTransito } = particionarPorUnidade(lista, indice, alvo.cod);
-                // A classificação cruza a folha (fonte administrativa) com o organograma (fonte institucional).
-                const provComEstrutura = withFieldSources(prov, [
-                    {
-                        fields: ["subordinadasA", "total", "naoClassificados"],
-                        source_url: provenanceEstrutura().source_url,
-                        dataset_id: "estrutura-organizacional",
-                        retrieved_at: ESTRUTURA_VINTAGE,
-                    },
-                ]);
+                const provComEstrutura = provenanceServidoresSubordinadas(prov, situacao);
                 return resultWithProvenance({
                     situacao,
                     subordinadasA: { sigla: alvo.sigla, nome: alvo.nome },

package/dist/utils/provenance.js

@@ -1,6 +1,6 @@
 /**
  * Vetor A — Proveniência no payload, contrato do portfólio (pacote
- * `@sbissoli/mcp-provenance` 0.3.0: contrato v1.2 publicado, v1.1 emitida por padrão).
+ * `@sbissoli/mcp-provenance`; a versão EMITIDA é `provenanceContext.contractVersion`).
  *
  * pt-BR adapter over `@sbissoli/mcp-provenance`: o modelo canônico, os modos
  * (`concise`/`detailed`), o determinismo de serialização, o fuso e o rodapé vivem no
@@ -14,14 +14,17 @@
  *  - v1.0 (release 3.5.0): `structuredContent.provenance` e o espelho em `_meta`
  *    passam a ser a projeção **concise** do contrato, com `null` explícito quando
  *    desconhecido (antes: campos opcionais omitidos).
- *  - v1.1 (release 3.11.0, a que este servidor EMITE — `contractVersion` default do
- *    pacote): o concise tem exatamente 7 chaves — `source`, `source_url`,
+ *  - v1.1 (release 3.11.0): o concise tem 7 chaves fixas — `source`, `source_url`,
  *    `data_vintage` (ex-`reference_period`), `retrieved_at`, `citation`, `license` e
  *    `retrieval` (diagnóstico medido da ida à origem, ou `null`).
- *  - v1.2 (aceita pelos schemas desde o pacote 0.3.0, NÃO ligada aqui): acrescenta ao
- *    concise a chave opcional `field_sources` (sub-fontes por campo; item com
- *    `served_from_cache` opcional). O `outputSchema` já a declara; ligar
- *    `contractVersion: "1.2"` é um passo separado.
+ *  - v1.2 (EMITIDA desde a release 3.17.0): acrescenta ao concise a chave opcional
+ *    `field_sources` (sub-fontes por campo), só nas respostas que fundem recortes. Com
+ *    ela a lib COBRA que o `retrieved_at` do topo seja o mais antigo entre as sub-fontes
+ *    (lança `ProvenanceContractError`, o que derrubaria a tool) — por isso o adaptador
+ *    o deriva por construção (`oldestRetrievedAt`), nunca a tool à mão.
+ *  - v1.3 (declarada pelo `outputSchema` desde a 3.17.0, ainda NÃO emitida): `notices`,
+ *    `derived`/`derivation_note` e `revision`. A `revision` já é informada aqui, por
+ *    fonte (`SOURCES`), e a lib a descarta enquanto o servidor emitir 1.2.
  *  - O rodapé de texto segue a redação fixada do contrato: linha de fonte
  *    ("Fonte: … · url · dados de … · extraído em …"), linha de licença e o aviso ao
  *    leitor de que a referência completa pode ser solicitada na própria conversa.
@@ -54,6 +57,7 @@ export const provenanceContext = createProvenanceContext({
     locale: "pt-BR",
     timezone: { offset: "-03:00", label: "horário de Brasília" },
     defaultMode: "concise",
+    contractVersion: "1.2",
 });
 const BRASILIA = provenanceContext.timezone;
 /**
@@ -75,16 +79,57 @@ const toCanonicalFieldSource = (fs) => ({
     data_vintage: fs.reference_period ?? null,
     retrieved_at: fs.retrieved_at ?? null,
 });
-const extraToCanonical = (extra = {}) => ({
-    ...(extra.dataset_id !== undefined ? { dataset: extra.dataset_id } : {}),
-    ...(extra.reference_period !== undefined ? { data_vintage: extra.reference_period } : {}),
-    ...(extra.retrieved_at !== undefined ? { retrieved_at: extra.retrieved_at } : {}),
-    ...(extra.api_version !== undefined ? { api_version: extra.api_version } : {}),
-    ...(extra.field_sources !== undefined
-        ? { field_sources: extra.field_sources.map(toCanonicalFieldSource) }
-        : {}),
-    retrieval: extra.retrieval !== undefined ? extra.retrieval : currentRetrieval(),
-});
+/**
+ * `retrieved_at` do topo de uma resposta que funde sub-fontes: o MAIS ANTIGO entre o
+ * topo informado e as sub-fontes (contrato §3, "nada aqui é mais velho que isto"). A
+ * partir da v1.2 a lib lança `ProvenanceContractError` se o topo for mais novo que
+ * alguma sub-fonte — e o erro derruba a tool. Derivar aqui, no único ponto por onde
+ * passam todas as `field_sources`, torna a regra verdadeira por construção: nenhuma
+ * tool escolhe o instante do topo à mão. Sub-fonte sem instante (`undefined`/`null`)
+ * não conta; sem topo informado, o mais antigo das sub-fontes substitui o "agora" que
+ * o builder usaria (que seria mais novo que elas).
+ */
+export function oldestRetrievedAt(top, fieldSources) {
+    let oldest = top;
+    let oldestMs = top !== undefined ? Date.parse(top) : Number.NaN;
+    for (const fs of fieldSources ?? []) {
+        if (fs.retrieved_at == null)
+            continue;
+        const ms = Date.parse(fs.retrieved_at);
+        if (Number.isNaN(ms))
+            continue;
+        if (oldest === undefined || Number.isNaN(oldestMs) || ms < oldestMs) {
+            oldest = fs.retrieved_at;
+            oldestMs = ms;
+        }
+    }
+    return oldest;
+}
+const extraToCanonical = (extra = {}) => {
+    const retrieved_at = oldestRetrievedAt(extra.retrieved_at, extra.field_sources);
+    return {
+        ...(extra.dataset_id !== undefined ? { dataset: extra.dataset_id } : {}),
+        ...(extra.reference_period !== undefined ? { data_vintage: extra.reference_period } : {}),
+        ...(retrieved_at !== undefined ? { retrieved_at } : {}),
+        ...(extra.api_version !== undefined ? { api_version: extra.api_version } : {}),
+        ...(extra.field_sources !== undefined
+            ? { field_sources: extra.field_sources.map(toCanonicalFieldSource) }
+            : {}),
+        retrieval: extra.retrieval !== undefined ? extra.retrieval : currentRetrieval(),
+    };
+};
+/**
+ * Situação de revisão por fonte (contrato v1.3, `revision`; decisão do dono de 08/10/2026:
+ * `current` em todas as fontes do senado, `final` em nenhuma — só com prova da fonte).
+ * A `note` só repete o que o servidor JÁ diz nas instructions (`src/app-surface.ts`) sobre
+ * os dados administrativos; nas demais fontes não há texto publicado, então `null`.
+ * Enquanto o servidor emitir a v1.2 a lib descarta o campo do fio — fica no canônico.
+ */
+const REVISAO_VIGENTE = { status: "current", note: null };
+const REVISAO_ADMINISTRATIVA = {
+    status: "current",
+    note: "Dados administrativos são os que o Senado publica no instante da extração e podem ser corrigidos depois.",
+};
 /** Metadados estáticos por fonte upstream. source_url é montado por chamada (endpoint real). */
 export const SOURCES = {
     /** API legislativa — legis.senado.leg.br/dadosabertos (votações, processos, matérias…). */
@@ -92,36 +137,42 @@ export const SOURCES = {
         source: "Senado Federal — Dados Abertos (Legislativo)",
         citation: "Fonte: Senado Federal, Portal de Dados Abertos (Legislativo) — legis.senado.leg.br/dadosabertos.",
         license: "Dados Abertos do Senado Federal — uso livre com atribuição da fonte.",
+        revision: REVISAO_VIGENTE,
     },
     /** API administrativa — adm.senado.gov.br/adm-dadosabertos (CEAPS, folha, contratos…). */
     SENADO_ADM: {
         source: "Senado Federal — Dados Abertos (Administrativo)",
         citation: "Fonte: Senado Federal, Portal de Dados Abertos (Administrativo) — adm.senado.gov.br/adm-dadosabertos.",
         license: "Dados Abertos do Senado Federal — uso livre com atribuição da fonte.",
+        revision: REVISAO_ADMINISTRATIVA,
     },
     /** Portal institucional — estrutura organizacional (www12.senado.leg.br/institucional/estrutura). */
     SENADO_INSTITUCIONAL: {
         source: "Senado Federal — Portal Institucional (Estrutura Organizacional)",
         citation: "Fonte: Senado Federal, Portal Institucional — Estrutura Organizacional (www12.senado.leg.br/institucional/estrutura).",
         license: "Dados Abertos do Senado Federal — uso livre com atribuição da fonte.",
+        revision: REVISAO_VIGENTE,
     },
     /** Portal e-Cidadania — www12.senado.leg.br/ecidadania. */
     ECIDADANIA: {
         source: "Senado Federal — Portal e-Cidadania",
         citation: "Fonte: Senado Federal, Portal e-Cidadania — www12.senado.leg.br/ecidadania.",
         license: "Dados Abertos do Senado Federal — uso livre com atribuição da fonte.",
+        revision: REVISAO_VIGENTE,
     },
     /** Feed de execução orçamentária/financeira — www.senado.gov.br/bi-arqs/Arquimedes/Financeiro. */
     SENADO_ORCAMENTO_EXEC: {
         source: "Senado Federal — Execução Orçamentária e Financeira",
         citation: "Fonte: Senado Federal — Dados Abertos Orçamentários (Arquimedes/Financeiro) — senado.gov.br.",
         license: "Dados Abertos do Senado Federal — uso livre com atribuição da fonte.",
+        revision: REVISAO_ADMINISTRATIVA,
     },
     /** Acervo histórico de votos das consultas e-Cidadania — CSV Arquimedes (bi-arqs/.../ecidadania). */
     ECIDADANIA_ARQUIMEDES: {
         source: "Senado Federal — e-Cidadania (acervo histórico de votos, Arquimedes)",
         citation: "Fonte: Senado Federal — e-Cidadania, acervo de votos por matéria/UF (Arquimedes/DadosAbertos) — senado.gov.br.",
         license: "Dados Abertos do Senado Federal — uso livre com atribuição da fonte.",
+        revision: REVISAO_VIGENTE,
     },
 };
 /** URL canônica do CSV Arquimedes de votos das consultas e-Cidadania (source_url da proveniência). */
@@ -133,12 +184,13 @@ export const ECIDADANIA_ARQUIMEDES_CSV_URL = "https://www.senado.gov.br/bi-arqs/
  * camada de cache.
  */
 export function buildProvenance(input) {
-    const { source, source_url, citation, license, ...extra } = input;
+    const { source, source_url, citation, license, revision, ...extra } = input;
     return provenanceContext.build({
         source,
         source_url,
         citation,
         license,
+        ...(revision !== undefined ? { revision } : {}),
         ...extraToCanonical(extra),
     });
 }
@@ -189,12 +241,15 @@ export function provenanceArquimedesVotos(extra) {
 export function withFieldSources(prov, fieldSources) {
     if (fieldSources.length === 0)
         return prov;
+    // O topo passa a ser o mais antigo entre ele e as sub-fontes (ver `oldestRetrievedAt`).
+    const retrieved_at = oldestRetrievedAt(prov.retrieved_at, fieldSources) ?? prov.retrieved_at;
     return provenanceContext.build({
         ...prov,
+        retrieved_at,
         field_sources: fieldSources.map(toCanonicalFieldSource),
     });
 }
-/** Rodapé de texto (contrato v1.0): fonte · url · vintage · extração, licença e aviso ao leitor. */
+/** Rodapé de texto do contrato: fonte · url · vintage · extração, licença e aviso ao leitor. */
 export const provenanceFooter = (p) => provenanceContext.footer(p);
 /**
  * Chaves namespaced do espelho em `_meta` (nível de resultado). O prefixo reverse-DNS

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.16.0";
+export const VERSION = "3.18.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.16.0",
+  "version": "3.18.0",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "license": "MIT",
   "type": "module",
@@ -51,10 +51,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
-    "@sbissoli/mcp-provenance": "^0.3.0",
+    "@sbissoli/mcp-provenance": "^0.4.0",
     "@sbissoli/mcp-search": "^0.9.0",
     "@sbissoli/mcp-stats": "^0.3.0",
-    "@sbissoli/mcp-upstream": "^0.4.0",
+    "@sbissoli/mcp-upstream": "^0.4.2",
     "zod": "^4.5.4"
   },
   "devDependencies": {