@sbissoli/mcp-provenance 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @sbissoli/mcp-provenance
+
+Contrato de proveniência para servidores MCP: todo retorno de tool carrega **fonte,
+endpoint, período, data de extração e licença**, com serialização determinística, em dois
+modos — `concise` (padrão, piso legal) e `detailed` (bloco canônico completo).
+
+> Mantido para o meu portfólio de servidores MCP. Uso por terceiros é bem-vindo, mas o
+> roadmap segue as necessidades dos meus servidores.
+
+Especificação completa: [`docs/contrato-proveniencia-v1.md`](docs/contrato-proveniencia-v1.md).
+
+## Uso
+
+```ts
+import { createProvenanceContext } from "@sbissoli/mcp-provenance";
+
+// 1. Uma vez, na inicialização do servidor:
+const prov = createProvenanceContext({
+  metaNamespace: "com.sidneybissoli.senado",   // chaves de _meta (reverse-DNS, estável)
+  locale: "pt-BR",                             // idioma do rodapé ("pt-BR" | "en" | LocaleSpec)
+  timezone: { offset: "-03:00", label: "horário de Brasília" }, // default: "utc"
+  defaultMode: "concise",                      // default: "concise"
+});
+
+// 2. Presets por fonte upstream (opcional):
+const SENADO_LEGIS = {
+  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.",
+};
+
+// 3. Em cada tool:
+const p = prov.from(SENADO_LEGIS, {
+  source_url: `${baseUrl}/processo.json`,
+  retrieved_at: fetchedAt,        // instante REAL da extração (preservado pelo cache)
+  data_vintage: "2025",
+});
+return prov.result(shapedData, p);                      // modo concise (default)
+return prov.result(shapedData, p, { mode: "detailed" }); // bloco canônico completo
+```
+
+`result()` emite os três canais: `structuredContent` (bloco + `attribution` RFC #711,
+visível ao modelo), `_meta` namespaced (auditoria/UI, zero tokens) e rodapé de texto
+compacto para clientes text-only.
+
+### Fonte estruturada (ex.: ILOSTAT/SDMX)
+
+```ts
+const p = prov.build({
+  source: { name: "ILOSTAT", agency: "ILO", database: "ILOSTAT", endpoint: "https://sdmx.ilo.org/rest" },
+  dataset: { id: "DF_UNE_DEAP_SEX_AGE_RT", version: "1.0", name: "Unemployment rate by sex and age" },
+  dimension_key: { REF_AREA: "BRA", SEX: "SEX_F", TIME_PERIOD: "2024" },
+  data_vintage: "2026-06-15",
+  retrieved_at: fetchedAt,
+  source_url: canonicalRestUrl,
+  license: { id: "CC-BY-4.0", url: "https://creativecommons.org/licenses/by/4.0/", verified_at: "2026-08-04" },
+  citation: "International Labour Organization, ILOSTAT, https://ilostat.ilo.org/data/, accessed 2026-08-04.",
+});
+```
+
+### Multi-fonte (segregação de licenças)
+
+```ts
+// Um bloco POR FONTE; dados de cada fonte em estruturas separadas apontando para o seu bloco.
+return prov.result({ ilostat: dadosIlo, uis: dadosUis }, [pIlo, pUis]);
+```
+
+### Recortes múltiplos de uma mesma fonte
+
+```ts
+const p = prov.build({ ...base, field_sources: [
+  { fields: ["relatoria"], source_url: urlRelatoria, retrieved_at: fetchedAtRelatoria },
+]});
+```
+
+## Regras que a lib impõe (server-side, antes de responder)
+
+- `license` com ao menos `id` ou `name` (piso legal);
+- `derived: true` exige `derivation_note`;
+- chaves em ordem fixa e ausência como `null` explícito (determinismo byte-a-byte por modo);
+- timestamps ISO-8601 sem milissegundos, normalizados ao fuso configurado (datas puras
+  passam intactas — nunca inventa horário num vintage).
+
+## API
+
+`createProvenanceContext(options)` → `{ build, from, render, footer, result, metaKeys }`.
+Peças soltas também exportadas: `CanonicalProvenanceSchema`, `renderConcise`,
+`renderDetailed`, `attributionList`, `provenanceFooter`, `toCanonicalIso`, locales
+`ptBR`/`en`.

package/dist/context.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Fábrica de contexto: o servidor cria UM contexto na inicialização (namespace de
+ * `_meta`, idioma, fuso, modo default) e as tools usam os helpers ligados a ele.
+ *
+ * Três canais para o mesmo envelope (estratégia herdada do senado-br-mcp):
+ *  1. `structuredContent.provenance` + `structuredContent.attribution` — canal
+ *     PARSEÁVEL e visível ao modelo (para que ele cite fonte/período/extração).
+ *  2. `_meta` sob chaves namespaced — metadado out-of-band (auditoria/UI), não custa
+ *     tokens do modelo; forward-compat com a Extensions Track de trust/attribution do
+ *     MCP (RFC #711 → PR #1913).
+ *  3. Linha de fonte compacta anexada ao `content` textual, para clientes text-only.
+ *
+ * O bloco embutido nos canais 1 e 2 é a PROJEÇÃO do modo da resposta (concise por
+ * padrão — decisão 5); `attribution` é sempre a lista canônica de `source_url`.
+ */
+import { type LocaleSpec } from "./locale.js";
+import { type ConciseBlock, type DetailedBlock, type ProvenanceMode } from "./render.js";
+import { type CanonicalProvenance, type ProvenanceInput } from "./schema.js";
+import { type TimezoneSpec } from "./time.js";
+export interface ProvenanceContextOptions {
+    /**
+     * Namespace reverse-DNS das chaves de `_meta` (ex.: "com.sidneybissoli.senado").
+     * Evita colisão com os namespaces reservados do MCP (`modelcontextprotocol.io/`,
+     * `mcp.*`) e com `openai/...`. Manter estável — consumidores leem por estas chaves.
+     */
+    metaNamespace: string;
+    /** Idioma do rodapé humano — "pt-BR", "en" ou um LocaleSpec customizado. */
+    locale?: string | LocaleSpec;
+    /** Fuso de serialização dos timestamps. Default: "utc". */
+    timezone?: TimezoneSpec;
+    /** Modo default das respostas. Default: "concise" (decisão 5). */
+    defaultMode?: ProvenanceMode;
+}
+/** Preset de fonte: campos fixos por fonte upstream; o restante vem por chamada. */
+export type SourcePreset = Pick<ProvenanceInput, "source" | "citation" | "license"> & Partial<Pick<ProvenanceInput, "dataset" | "api_version" | "notices">>;
+export interface ProvenanceResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent: Record<string, unknown> & {
+        provenance: ConciseBlock | DetailedBlock | Array<ConciseBlock | DetailedBlock>;
+        attribution: string[];
+    };
+    _meta: Record<string, unknown>;
+}
+export interface ProvenanceContext {
+    metaKeys: {
+        provenance: string;
+        attribution: string;
+    };
+    locale: LocaleSpec;
+    timezone: TimezoneSpec;
+    defaultMode: ProvenanceMode;
+    /** Valida e normaliza a entrada no modelo canônico (fuso aplicado a retrieved_at). */
+    build(input: ProvenanceInput): CanonicalProvenance;
+    /** `build` a partir de um preset de fonte + campos por chamada. */
+    from(preset: SourcePreset, perCall: Omit<ProvenanceInput, keyof SourcePreset> & Partial<SourcePreset>): CanonicalProvenance;
+    /** Projeção do bloco no modo pedido (default do contexto). */
+    render(p: CanonicalProvenance, mode?: ProvenanceMode): ConciseBlock | DetailedBlock;
+    /** Rodapé humano para os blocos, no idioma/fuso do contexto. */
+    footer(p: CanonicalProvenance | CanonicalProvenance[], mode?: ProvenanceMode): string;
+    /** Resultado MCP completo: os três canais. `data` deve ser um objeto. */
+    result(data: Record<string, unknown>, provenance: CanonicalProvenance | CanonicalProvenance[], opts?: {
+        mode?: ProvenanceMode;
+    }): ProvenanceResult;
+}
+export declare function createProvenanceContext(options: ProvenanceContextOptions): ProvenanceContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE7E,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,kEAAkE;IAClE,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,oFAAoF;AACpF,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC,GACjF,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,aAAa,GAAG,SAAS,CAAC,CAAC,CAAC;AAExE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAC3C,UAAU,EAAE,YAAY,GAAG,aAAa,GAAG,KAAK,CAAC,YAAY,GAAG,aAAa,CAAC,CAAC;QAC/E,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,EAAE,cAAc,CAAC;IAC5B,sFAAsF;IACtF,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAAC;IACnD,mEAAmE;IACnE,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,YAAY,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,mBAAmB,CAAC;IAC5H,8DAA8D;IAC9D,MAAM,CAAC,CAAC,EAAE,mBAAmB,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,YAAY,GAAG,aAAa,CAAC;IACpF,gEAAgE;IAChE,MAAM,CAAC,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,EAAE,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;IACtF,yEAAyE;IACzE,MAAM,CACJ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,mBAAmB,GAAG,mBAAmB,EAAE,EACvD,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,cAAc,CAAA;KAAE,GAC/B,gBAAgB,CAAC;CACrB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CA+D5F"}

package/dist/context.js

@@ -0,0 +1,72 @@
+/**
+ * Fábrica de contexto: o servidor cria UM contexto na inicialização (namespace de
+ * `_meta`, idioma, fuso, modo default) e as tools usam os helpers ligados a ele.
+ *
+ * Três canais para o mesmo envelope (estratégia herdada do senado-br-mcp):
+ *  1. `structuredContent.provenance` + `structuredContent.attribution` — canal
+ *     PARSEÁVEL e visível ao modelo (para que ele cite fonte/período/extração).
+ *  2. `_meta` sob chaves namespaced — metadado out-of-band (auditoria/UI), não custa
+ *     tokens do modelo; forward-compat com a Extensions Track de trust/attribution do
+ *     MCP (RFC #711 → PR #1913).
+ *  3. Linha de fonte compacta anexada ao `content` textual, para clientes text-only.
+ *
+ * O bloco embutido nos canais 1 e 2 é a PROJEÇÃO do modo da resposta (concise por
+ * padrão — decisão 5); `attribution` é sempre a lista canônica de `source_url`.
+ */
+import { provenanceFooter } from "./footer.js";
+import { resolveLocale } from "./locale.js";
+import { attributionList, renderProvenance, } from "./render.js";
+import { assertSemantics, CanonicalProvenanceSchema, expandInput, } from "./schema.js";
+import { timezoneLabel, toCanonicalIso } from "./time.js";
+export function createProvenanceContext(options) {
+    const locale = resolveLocale(options.locale ?? "pt-BR");
+    const timezone = options.timezone ?? "utc";
+    const defaultMode = options.defaultMode ?? "concise";
+    const ns = options.metaNamespace.replace(/\/+$/, "");
+    if (!ns)
+        throw new Error("metaNamespace é obrigatório (ex.: \"com.exemplo.meuservidor\")");
+    const metaKeys = { provenance: `${ns}/provenance`, attribution: `${ns}/attribution` };
+    const tzLabel = timezoneLabel(timezone);
+    function build(input) {
+        const retrievedAtIso = toCanonicalIso(input.retrieved_at ?? new Date(), timezone);
+        const expanded = expandInput(input, retrievedAtIso);
+        if (expanded.field_sources) {
+            expanded.field_sources = expanded.field_sources.map((fs) => fs.retrieved_at ? { ...fs, retrieved_at: toCanonicalIso(fs.retrieved_at, timezone) } : fs);
+        }
+        const parsed = CanonicalProvenanceSchema.parse(expanded);
+        assertSemantics(parsed);
+        return parsed;
+    }
+    function from(preset, perCall) {
+        return build({ ...preset, ...perCall });
+    }
+    function render(p, mode) {
+        return renderProvenance(p, mode ?? defaultMode);
+    }
+    function footer(p, mode) {
+        const blocks = Array.isArray(p) ? p : [p];
+        return provenanceFooter(blocks, { locale, tzLabel, mode: mode ?? defaultMode });
+    }
+    function result(data, provenance, opts) {
+        const mode = opts?.mode ?? defaultMode;
+        const blocks = Array.isArray(provenance) ? provenance : [provenance];
+        if (blocks.length === 0)
+            throw new Error("result() exige ao menos um bloco de proveniência");
+        const rendered = blocks.map((b) => renderProvenance(b, mode));
+        const provOut = Array.isArray(provenance) ? rendered : rendered[0];
+        const attribution = attributionList(blocks);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+                { type: "text", text: footer(blocks, mode) },
+            ],
+            structuredContent: { ...data, provenance: provOut, attribution },
+            _meta: {
+                [metaKeys.provenance]: provOut,
+                [metaKeys.attribution]: attribution,
+            },
+        };
+    }
+    return { metaKeys, locale, timezone, defaultMode, build, from, render, footer, result };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/footer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Rodapé de fonte — o canal para clientes que só renderizam texto.
+ *
+ * Formato (uma dupla de linhas por fonte, respeitando a segregação por licença):
+ *
+ *   ---
+ *   Fonte: {nome} · {url} · dados de {vintage} · extraído em {timestamp humano}
+ *   Licença: {licença}.
+ *   A referência completa desta informação pode ser solicitada nesta própria conversa.
+ *
+ * O aviso final (requestNotice) aparece UMA vez, apenas no modo `concise` — no modo
+ * `detailed` a referência completa já está na própria resposta, e o aviso seria ruído.
+ */
+import type { LocaleSpec } from "./locale.js";
+import type { ProvenanceMode } from "./render.js";
+import type { CanonicalProvenance } from "./schema.js";
+export declare function provenanceFooter(blocks: CanonicalProvenance[], opts: {
+    locale: LocaleSpec;
+    tzLabel: string;
+    mode: ProvenanceMode;
+}): string;
+//# sourceMappingURL=footer.d.ts.map

package/dist/footer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"footer.d.ts","sourceRoot":"","sources":["../src/footer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,mBAAmB,EAAE,EAC7B,IAAI,EAAE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GAClE,MAAM,CAaR"}

package/dist/footer.js

@@ -0,0 +1,32 @@
+/**
+ * Rodapé de fonte — o canal para clientes que só renderizam texto.
+ *
+ * Formato (uma dupla de linhas por fonte, respeitando a segregação por licença):
+ *
+ *   ---
+ *   Fonte: {nome} · {url} · dados de {vintage} · extraído em {timestamp humano}
+ *   Licença: {licença}.
+ *   A referência completa desta informação pode ser solicitada nesta própria conversa.
+ *
+ * O aviso final (requestNotice) aparece UMA vez, apenas no modo `concise` — no modo
+ * `detailed` a referência completa já está na própria resposta, e o aviso seria ruído.
+ */
+import { conciseLicense } from "./render.js";
+export function provenanceFooter(blocks, opts) {
+    const { locale, tzLabel, mode } = opts;
+    const lines = ["---"];
+    for (const p of blocks) {
+        const parts = [`${locale.sourceLabel}: ${p.source.name}`, p.source_url];
+        if (p.data_vintage)
+            parts.push(`${locale.vintagePrefix} ${p.data_vintage}`);
+        parts.push(`${locale.retrievedPrefix} ${locale.formatTimestamp(p.retrieved_at, tzLabel)}`);
+        lines.push(parts.join(" · "));
+        const license = conciseLicense(p.license);
+        if (license)
+            lines.push(`${locale.licenseLabel}: ${license.endsWith(".") ? license : `${license}.`}`);
+    }
+    if (mode === "concise")
+        lines.push(locale.requestNotice);
+    return lines.join("\n");
+}
+//# sourceMappingURL=footer.js.map

package/dist/footer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"footer.js","sourceRoot":"","sources":["../src/footer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,MAAM,UAAU,gBAAgB,CAC9B,MAA6B,EAC7B,IAAmE;IAEnE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IACvC,MAAM,KAAK,GAAa,CAAC,KAAK,CAAC,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,WAAW,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;QACxE,IAAI,CAAC,CAAC,YAAY;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,aAAa,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;QAC5E,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,eAAe,IAAI,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,YAAY,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3F,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9B,MAAM,OAAO,GAAG,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,YAAY,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,EAAE,CAAC,CAAC;IACxG,CAAC;IACD,IAAI,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACzD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { CONTRACT_VERSION, CanonicalProvenanceSchema, DatasetSchema, FieldSourceSchema, LicenseSchema, ProvenanceContractError, SourceSchema, type CanonicalProvenance, type FieldSource, type ProvenanceInput, } from "./schema.js";
+export { attributionList, conciseLicense, renderConcise, renderDetailed, renderProvenance, type ConciseBlock, type DetailedBlock, type ProvenanceMode, } from "./render.js";
+export { en, locales, ptBR, resolveLocale, type LocaleSpec } from "./locale.js";
+export { provenanceFooter } from "./footer.js";
+export { parseOffsetMinutes, timezoneLabel, toCanonicalIso, type TimezoneSpec } from "./time.js";
+export { createProvenanceContext, type ProvenanceContext, type ProvenanceContextOptions, type ProvenanceResult, type SourcePreset, } from "./context.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,uBAAuB,EACvB,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AACjG,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { CONTRACT_VERSION, CanonicalProvenanceSchema, DatasetSchema, FieldSourceSchema, LicenseSchema, ProvenanceContractError, SourceSchema, } from "./schema.js";
+export { attributionList, conciseLicense, renderConcise, renderDetailed, renderProvenance, } from "./render.js";
+export { en, locales, ptBR, resolveLocale } from "./locale.js";
+export { provenanceFooter } from "./footer.js";
+export { parseOffsetMinutes, timezoneLabel, toCanonicalIso } from "./time.js";
+export { createProvenanceContext, } from "./context.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,uBAAuB,EACvB,YAAY,GAIb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,GAIjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAqB,MAAM,WAAW,CAAC;AACjG,OAAO,EACL,uBAAuB,GAKxB,MAAM,cAAc,CAAC"}

package/dist/locale.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Princípio de linguagem (decisão 5 da Fase 0): o rodapé fala com o LEITOR, o schema
+ * fala com o agente. O aviso no corpo da resposta é em linguagem simples, registro
+ * formal/institucional (público: pesquisadores, jornalistas, órgãos públicos), no
+ * idioma do servidor, sem jargão técnico ("proveniência", "response_format", inglês
+ * voltado ao usuário final) e sem coloquialidade. O aviso deixa explícito que a
+ * referência completa se solicita AQUI MESMO, na conversa — não em portal, e-mail ou
+ * outro canal.
+ *
+ * A redação pt-BR do aviso é a fixada na decisão 5; não alterar sem decisão nova.
+ */
+export interface LocaleSpec {
+    id: string;
+    /** "Fonte" / "Source" */
+    sourceLabel: string;
+    /** Prefixo do vintage: "dados de" / "data as of" */
+    vintagePrefix: string;
+    /** Prefixo da extração: "extraído em" / "retrieved on" */
+    retrievedPrefix: string;
+    /** "Licença" / "License" */
+    licenseLabel: string;
+    /** Aviso ao leitor de que a referência completa pode ser pedida na própria conversa. */
+    requestNotice: string;
+    /** Versão humana de um timestamp canônico ISO-8601 (datas puras sem hora). */
+    formatTimestamp(iso: string, tzLabel: string): string;
+}
+export declare const ptBR: LocaleSpec;
+export declare const en: LocaleSpec;
+export declare const locales: Record<string, LocaleSpec>;
+/** Resolve um id de locale embutido ou aceita um LocaleSpec customizado. */
+export declare function resolveLocale(locale: string | LocaleSpec): LocaleSpec;
+//# sourceMappingURL=locale.d.ts.map

package/dist/locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../src/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,aAAa,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CACvD;AAID,eAAO,MAAM,IAAI,EAAE,UAalB,CAAC;AAEF,eAAO,MAAM,EAAE,EAAE,UAahB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAyB,CAAC;AAEzE,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAOrE"}

package/dist/locale.js

@@ -0,0 +1,54 @@
+/**
+ * Princípio de linguagem (decisão 5 da Fase 0): o rodapé fala com o LEITOR, o schema
+ * fala com o agente. O aviso no corpo da resposta é em linguagem simples, registro
+ * formal/institucional (público: pesquisadores, jornalistas, órgãos públicos), no
+ * idioma do servidor, sem jargão técnico ("proveniência", "response_format", inglês
+ * voltado ao usuário final) e sem coloquialidade. O aviso deixa explícito que a
+ * referência completa se solicita AQUI MESMO, na conversa — não em portal, e-mail ou
+ * outro canal.
+ *
+ * A redação pt-BR do aviso é a fixada na decisão 5; não alterar sem decisão nova.
+ */
+const ISO_RE = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}))?/;
+export const ptBR = {
+    id: "pt-BR",
+    sourceLabel: "Fonte",
+    vintagePrefix: "dados de",
+    retrievedPrefix: "extraído em",
+    licenseLabel: "Licença",
+    requestNotice: "A referência completa desta informação pode ser solicitada nesta própria conversa.",
+    formatTimestamp(iso, tzLabel) {
+        const m = iso.match(ISO_RE);
+        if (!m)
+            return iso;
+        const [, y, mo, d, hh, mm] = m;
+        return hh !== undefined ? `${d}/${mo}/${y} às ${hh}:${mm} (${tzLabel})` : `${d}/${mo}/${y}`;
+    },
+};
+export const en = {
+    id: "en",
+    sourceLabel: "Source",
+    vintagePrefix: "data as of",
+    retrievedPrefix: "retrieved on",
+    licenseLabel: "License",
+    requestNotice: "The complete reference for this information can be requested here, in this same conversation.",
+    formatTimestamp(iso, tzLabel) {
+        const m = iso.match(ISO_RE);
+        if (!m)
+            return iso;
+        const [, y, mo, d, hh, mm] = m;
+        return hh !== undefined ? `${y}-${mo}-${d}, ${hh}:${mm} (${tzLabel})` : `${y}-${mo}-${d}`;
+    },
+};
+export const locales = { "pt-BR": ptBR, en };
+/** Resolve um id de locale embutido ou aceita um LocaleSpec customizado. */
+export function resolveLocale(locale) {
+    if (typeof locale !== "string")
+        return locale;
+    const found = locales[locale];
+    if (!found) {
+        throw new Error(`Locale desconhecido: "${locale}" (embutidos: ${Object.keys(locales).join(", ")}); passe um LocaleSpec customizado`);
+    }
+    return found;
+}
+//# sourceMappingURL=locale.js.map

package/dist/locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.js","sourceRoot":"","sources":["../src/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkBH,MAAM,MAAM,GAAG,+CAA+C,CAAC;AAE/D,MAAM,CAAC,MAAM,IAAI,GAAe;IAC9B,EAAE,EAAE,OAAO;IACX,WAAW,EAAE,OAAO;IACpB,aAAa,EAAE,UAAU;IACzB,eAAe,EAAE,aAAa;IAC9B,YAAY,EAAE,SAAS;IACvB,aAAa,EAAE,oFAAoF;IACnG,eAAe,CAAC,GAAG,EAAE,OAAO;QAC1B,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QACnB,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;IAC9F,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,EAAE,GAAe;IAC5B,EAAE,EAAE,IAAI;IACR,WAAW,EAAE,QAAQ;IACrB,aAAa,EAAE,YAAY;IAC3B,eAAe,EAAE,cAAc;IAC/B,YAAY,EAAE,SAAS;IACvB,aAAa,EAAE,+FAA+F;IAC9G,eAAe,CAAC,GAAG,EAAE,OAAO;QAC1B,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QACnB,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;IAC5F,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAA+B,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAEzE,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAAC,MAA2B;IACvD,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,iBAAiB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACvI,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Projeções por modo do bloco de proveniência (decisão 5 da Fase 0).
+ *
+ * - `concise` (padrão): piso legal + citação mínima — fonte, URL canônica, vintage,
+ *   data de extração, citação/atribuição, licença. Seis chaves, sempre presentes,
+ *   `null` explícito quando desconhecido.
+ * - `detailed`: bloco canônico completo do contrato v1.0, todas as chaves em ordem
+ *   fixa, ausência = `null` explícito.
+ *
+ * DETERMINISMO: os objetos são construídos literalmente em ordem fixa de chaves —
+ * `JSON.stringify` preserva a ordem de inserção, logo a mesma consulta sobre a mesma
+ * versão dos dados produz bloco byte-idêntico exceto pelos campos de timestamp
+ * (`retrieved_at`, citação que embute data). Não reordenar campos: a ordem é contrato.
+ */
+import type { CanonicalProvenance, FieldSource } from "./schema.js";
+export type ProvenanceMode = "concise" | "detailed";
+/** Projeção concise — chaves e ordem fazem parte do contrato. */
+export interface ConciseBlock {
+    source: string;
+    source_url: string;
+    data_vintage: string | null;
+    retrieved_at: string;
+    citation: string;
+    license: string | null;
+}
+/** Rótulo curto da licença para o modo concise: `id` quando há, senão `name`. */
+export declare function conciseLicense(license: CanonicalProvenance["license"]): string | null;
+export declare function renderConcise(p: CanonicalProvenance): ConciseBlock;
+/** Projeção detailed — o bloco canônico completo, ordem fixa, nulls explícitos. */
+export interface DetailedBlock {
+    contract_version: string;
+    source: {
+        name: string;
+        agency: string | null;
+        database: string | null;
+        endpoint: string | null;
+    };
+    dataset: {
+        id: string | null;
+        version: string | null;
+        name: string | null;
+    };
+    dimension_key: Record<string, string> | null;
+    data_vintage: string | null;
+    retrieved_at: string;
+    source_url: string;
+    api_version: string | null;
+    license: {
+        id: string | null;
+        name: string | null;
+        url: string | null;
+        terms_url: string | null;
+        verified_at: string | null;
+    };
+    citation: string;
+    notices: string[];
+    derived: boolean;
+    derivation_note: string | null;
+    served_from_cache: boolean | null;
+    field_sources: FieldSource[] | null;
+}
+export declare function renderDetailed(p: CanonicalProvenance): DetailedBlock;
+export declare function renderProvenance(p: CanonicalProvenance, mode: ProvenanceMode): ConciseBlock | DetailedBlock;
+/**
+ * Lista canônica de fontes no formato da RFC `attribution` do MCP
+ * (modelcontextprotocol#711): todas as `source_url` distintas da resposta, incluindo
+ * as de `field_sources`, na ordem de primeira aparição.
+ */
+export declare function attributionList(blocks: CanonicalProvenance[]): string[];
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEpE,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpD,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,CAErF;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,mBAAmB,GAAG,YAAY,CASlE;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAClG,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC5E,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7C,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,aAAa,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;CACrC;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAqCpE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,mBAAmB,EAAE,IAAI,EAAE,cAAc,GAAG,YAAY,GAAG,aAAa,CAE3G;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAMvE"}

package/dist/render.js

@@ -0,0 +1,82 @@
+/**
+ * Projeções por modo do bloco de proveniência (decisão 5 da Fase 0).
+ *
+ * - `concise` (padrão): piso legal + citação mínima — fonte, URL canônica, vintage,
+ *   data de extração, citação/atribuição, licença. Seis chaves, sempre presentes,
+ *   `null` explícito quando desconhecido.
+ * - `detailed`: bloco canônico completo do contrato v1.0, todas as chaves em ordem
+ *   fixa, ausência = `null` explícito.
+ *
+ * DETERMINISMO: os objetos são construídos literalmente em ordem fixa de chaves —
+ * `JSON.stringify` preserva a ordem de inserção, logo a mesma consulta sobre a mesma
+ * versão dos dados produz bloco byte-idêntico exceto pelos campos de timestamp
+ * (`retrieved_at`, citação que embute data). Não reordenar campos: a ordem é contrato.
+ */
+/** Rótulo curto da licença para o modo concise: `id` quando há, senão `name`. */
+export function conciseLicense(license) {
+    return license.id ?? license.name;
+}
+export function renderConcise(p) {
+    return {
+        source: p.source.name,
+        source_url: p.source_url,
+        data_vintage: p.data_vintage,
+        retrieved_at: p.retrieved_at,
+        citation: p.citation,
+        license: conciseLicense(p.license),
+    };
+}
+export function renderDetailed(p) {
+    return {
+        contract_version: p.contract_version,
+        source: {
+            name: p.source.name,
+            agency: p.source.agency,
+            database: p.source.database,
+            endpoint: p.source.endpoint,
+        },
+        dataset: { id: p.dataset.id, version: p.dataset.version, name: p.dataset.name },
+        dimension_key: p.dimension_key,
+        data_vintage: p.data_vintage,
+        retrieved_at: p.retrieved_at,
+        source_url: p.source_url,
+        api_version: p.api_version,
+        license: {
+            id: p.license.id,
+            name: p.license.name,
+            url: p.license.url,
+            terms_url: p.license.terms_url,
+            verified_at: p.license.verified_at,
+        },
+        citation: p.citation,
+        notices: [...p.notices],
+        derived: p.derived,
+        derivation_note: p.derivation_note,
+        served_from_cache: p.served_from_cache,
+        field_sources: p.field_sources
+            ? p.field_sources.map((fs) => ({
+                fields: [...fs.fields],
+                source_url: fs.source_url,
+                dataset_id: fs.dataset_id,
+                data_vintage: fs.data_vintage,
+                retrieved_at: fs.retrieved_at,
+            }))
+            : null,
+    };
+}
+export function renderProvenance(p, mode) {
+    return mode === "concise" ? renderConcise(p) : renderDetailed(p);
+}
+/**
+ * Lista canônica de fontes no formato da RFC `attribution` do MCP
+ * (modelcontextprotocol#711): todas as `source_url` distintas da resposta, incluindo
+ * as de `field_sources`, na ordem de primeira aparição.
+ */
+export function attributionList(blocks) {
+    const urls = [];
+    for (const p of blocks) {
+        urls.push(p.source_url, ...(p.field_sources?.map((fs) => fs.source_url) ?? []));
+    }
+    return [...new Set(urls)];
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Modelo canônico de proveniência — contrato v1.0 do portfólio.
+ *
+ * Generalização de duas linhagens em produção/rascunho:
+ *  - envelope nível-1 do senado-br-mcp-cloudflare (`src/utils/provenance.ts`) — vira a
+ *    projeção `concise`;
+ *  - bloco canônico v0.1 do ilostat (`docs/03-contrato-proveniencia.md`) — vira a
+ *    projeção `detailed`.
+ *
+ * O servidor constrói UM modelo canônico por fonte (validado aqui, server-side); a
+ * projeção por modo acontece em `render.ts`. Regra de segregação: um bloco refere-se a
+ * exatamente UMA fonte — resposta multi-fonte carrega um bloco por fonte, e os dados de
+ * cada fonte ficam em estruturas separadas apontando para seu bloco (não contaminar
+ * licenças distintas, ex.: CC BY vs. CC BY-SA).
+ */
+import { z } from "zod";
+/** Versão do contrato de proveniência implementado por esta lib. */
+export declare const CONTRACT_VERSION = "1.0";
+/** Identidade da fonte. `name` é o nome humano oficial; os demais refinam quando existem. */
+export declare const SourceSchema: z.ZodObject<{
+    name: z.ZodString;
+    agency: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    database: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    endpoint: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Identidade do conjunto de dados dentro da fonte (dataflow SDMX, tabela, série…). */
+export declare const DatasetSchema: z.ZodObject<{
+    id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    version: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Regime legal do dado. Ao menos `id` ou `name` deve estar presente (piso legal). */
+export declare const LicenseSchema: z.ZodObject<{
+    id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    terms_url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    verified_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Sub-fonte por campo — para respostas que fundem recortes/endpoints numa única estrutura. */
+export declare const FieldSourceSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodString>;
+    source_url: z.ZodString;
+    dataset_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    data_vintage: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    retrieved_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type FieldSource = z.infer<typeof FieldSourceSchema>;
+/**
+ * Modelo canônico completo (pós-validação). `retrieved_at` deve ser o instante real da
+ * extração no upstream — preservado pela camada de cache do servidor —, nunca o momento
+ * do build/deploy; respostas servidas de cache mantêm o `retrieved_at` do fetch original
+ * (é a data de extração juridicamente relevante) e podem marcar `served_from_cache`.
+ */
+export declare const CanonicalProvenanceSchema: z.ZodObject<{
+    contract_version: z.ZodDefault<z.ZodLiteral<"1.0">>;
+    source: z.ZodObject<{
+        name: z.ZodString;
+        agency: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        database: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        endpoint: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    dataset: z.ZodDefault<z.ZodObject<{
+        id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        version: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    dimension_key: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    data_vintage: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    retrieved_at: z.ZodString;
+    source_url: z.ZodString;
+    api_version: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    license: z.ZodObject<{
+        id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        terms_url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        verified_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    citation: z.ZodString;
+    notices: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    derived: z.ZodDefault<z.ZodBoolean>;
+    derivation_note: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    served_from_cache: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
+    field_sources: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        fields: z.ZodArray<z.ZodString>;
+        source_url: z.ZodString;
+        dataset_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data_vintage: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        retrieved_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export type CanonicalProvenance = z.infer<typeof CanonicalProvenanceSchema>;
+/** Entrada aceita pelos builders: atalhos de string para source/dataset/license. */
+export interface ProvenanceInput {
+    source: string | z.input<typeof SourceSchema>;
+    source_url: string;
+    citation: string;
+    license: string | z.input<typeof LicenseSchema>;
+    dataset?: string | z.input<typeof DatasetSchema> | null;
+    dimension_key?: Record<string, string> | null;
+    data_vintage?: string | null;
+    /** Default: instante da chamada — aceitável só para catálogos estáticos sem extração upstream. */
+    retrieved_at?: string | Date;
+    api_version?: string | null;
+    notices?: string[];
+    derived?: boolean;
+    derivation_note?: string | null;
+    served_from_cache?: boolean | null;
+    field_sources?: Array<{
+        fields: string[];
+        source_url: string;
+        dataset_id?: string | null;
+        data_vintage?: string | null;
+        retrieved_at?: string | null;
+    }> | null;
+}
+/** Erro de contrato: builder recebeu entrada que viola o schema ou as regras semânticas. */
+export declare class ProvenanceContractError extends Error {
+    constructor(message: string);
+}
+/**
+ * Expande os atalhos de string da entrada para os objetos canônicos. `retrievedAtIso` é
+ * o instante já normalizado para o fuso do contexto (a normalização vive no builder,
+ * que conhece o `TimezoneSpec`).
+ */
+export declare function expandInput(input: ProvenanceInput, retrievedAtIso: string): z.input<typeof CanonicalProvenanceSchema>;
+/** Regras semânticas que o zod não cobre por campo isolado. */
+export declare function assertSemantics(p: CanonicalProvenance): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAItC,6FAA6F;AAC7F,eAAO,MAAM,YAAY;;;;;iBAKvB,CAAC;AAEH,uFAAuF;AACvF,eAAO,MAAM,aAAa;;;;iBAIxB,CAAC;AAEH,sFAAsF;AACtF,eAAO,MAAM,aAAa;;;;;;iBAUtB,CAAC;AAEL,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB;;;;;;iBAM5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;IAChD,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,GAAG,IAAI,CAAC;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,iBAAiB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,aAAa,CAAC,EAAE,KAAK,CAAC;QACpB,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B,CAAC,GAAG,IAAI,CAAC;CACX;AAED,4FAA4F;AAC5F,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,eAAe,EACtB,cAAc,EAAE,MAAM,GACrB,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAa3C;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAI5D"}

package/dist/schema.js

@@ -0,0 +1,122 @@
+/**
+ * Modelo canônico de proveniência — contrato v1.0 do portfólio.
+ *
+ * Generalização de duas linhagens em produção/rascunho:
+ *  - envelope nível-1 do senado-br-mcp-cloudflare (`src/utils/provenance.ts`) — vira a
+ *    projeção `concise`;
+ *  - bloco canônico v0.1 do ilostat (`docs/03-contrato-proveniencia.md`) — vira a
+ *    projeção `detailed`.
+ *
+ * O servidor constrói UM modelo canônico por fonte (validado aqui, server-side); a
+ * projeção por modo acontece em `render.ts`. Regra de segregação: um bloco refere-se a
+ * exatamente UMA fonte — resposta multi-fonte carrega um bloco por fonte, e os dados de
+ * cada fonte ficam em estruturas separadas apontando para seu bloco (não contaminar
+ * licenças distintas, ex.: CC BY vs. CC BY-SA).
+ */
+import { z } from "zod";
+/** Versão do contrato de proveniência implementado por esta lib. */
+export const CONTRACT_VERSION = "1.0";
+const nullableString = z.string().min(1).nullable().default(null);
+/** Identidade da fonte. `name` é o nome humano oficial; os demais refinam quando existem. */
+export const SourceSchema = z.object({
+    name: z.string().min(1).describe('Nome oficial da fonte (ex.: "Senado Federal — Dados Abertos (Legislativo)")'),
+    agency: nullableString.describe('Órgão/agência (ex.: "ILO", "Senado Federal")'),
+    database: nullableString.describe('Base/sistema dentro do órgão (ex.: "ILOSTAT")'),
+    endpoint: nullableString.describe("Endpoint-base efetivamente consultado"),
+});
+/** Identidade do conjunto de dados dentro da fonte (dataflow SDMX, tabela, série…). */
+export const DatasetSchema = z.object({
+    id: nullableString.describe("Identificador do conjunto (dataflow, código da matéria, série, tabela)"),
+    version: nullableString.describe("Versão do conjunto reportada pela fonte"),
+    name: nullableString.describe("Nome humano do conjunto, do metadado da fonte"),
+});
+/** Regime legal do dado. Ao menos `id` ou `name` deve estar presente (piso legal). */
+export const LicenseSchema = z
+    .object({
+    id: nullableString.describe('Identificador SPDX-like (ex.: "CC-BY-4.0")'),
+    name: nullableString.describe("Nome/descrição da licença quando não há identificador formal"),
+    url: nullableString.describe("URL do texto da licença"),
+    terms_url: nullableString.describe("URL dos termos de uso da fonte"),
+    verified_at: nullableString.describe("Data (ISO-8601) da última verificação verbatim da licença"),
+})
+    .refine((l) => l.id !== null || l.name !== null, {
+    message: "license exige ao menos `id` ou `name` (piso legal do contrato)",
+});
+/** Sub-fonte por campo — para respostas que fundem recortes/endpoints numa única estrutura. */
+export const FieldSourceSchema = z.object({
+    fields: z.array(z.string().min(1)).min(1).describe("Campos do payload atribuídos a esta sub-fonte"),
+    source_url: z.string().min(1).describe("URL canônica da sub-fonte que originou estes campos"),
+    dataset_id: nullableString.describe("Identificador do conjunto da sub-fonte"),
+    data_vintage: nullableString.describe("Vintage/competência da sub-fonte"),
+    retrieved_at: nullableString.describe("ISO-8601 da extração desta sub-fonte no upstream"),
+});
+/**
+ * Modelo canônico completo (pós-validação). `retrieved_at` deve ser o instante real da
+ * extração no upstream — preservado pela camada de cache do servidor —, nunca o momento
+ * do build/deploy; respostas servidas de cache mantêm o `retrieved_at` do fetch original
+ * (é a data de extração juridicamente relevante) e podem marcar `served_from_cache`.
+ */
+export const CanonicalProvenanceSchema = z.object({
+    contract_version: z.literal(CONTRACT_VERSION).default(CONTRACT_VERSION),
+    source: SourceSchema,
+    dataset: DatasetSchema.default({ id: null, version: null, name: null }),
+    dimension_key: z
+        .record(z.string(), z.string())
+        .nullable()
+        .default(null)
+        .describe("Chave dimensional da consulta (ordem = ordem das dimensões na fonte), quando aplicável"),
+    data_vintage: nullableString.describe("Vintage/competência do dado segundo a fonte; null se a fonte não expõe"),
+    retrieved_at: z.string().min(1).describe("ISO-8601 do momento da extração no upstream (não do build/deploy)"),
+    source_url: z.string().min(1).describe("URL canônica que reproduz a consulta na fonte"),
+    api_version: nullableString.describe("Versão do endpoint upstream, se exposta"),
+    license: LicenseSchema,
+    citation: z.string().min(1).describe("String de citação/atribuição pronta para uso (texto humano)"),
+    notices: z
+        .array(z.string().min(1))
+        .default([])
+        .describe("Disclaimers/avisos que acompanham o dado na origem, reproduzidos verbatim; [] se não houver"),
+    derived: z.boolean().default(false).describe("true se o servidor transformou além de filtrar/paginar/reserializar"),
+    derivation_note: nullableString.describe("Obrigatório se derived=true: o que foi feito"),
+    served_from_cache: z
+        .boolean()
+        .nullable()
+        .default(null)
+        .describe("true/false quando o servidor distingue cache de fetch; null quando não distingue"),
+    field_sources: z
+        .array(FieldSourceSchema)
+        .nullable()
+        .default(null)
+        .describe("Proveniência por-campo: presente só quando a resposta funde múltiplos recortes upstream"),
+});
+/** Erro de contrato: builder recebeu entrada que viola o schema ou as regras semânticas. */
+export class ProvenanceContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProvenanceContractError";
+    }
+}
+/**
+ * Expande os atalhos de string da entrada para os objetos canônicos. `retrievedAtIso` é
+ * o instante já normalizado para o fuso do contexto (a normalização vive no builder,
+ * que conhece o `TimezoneSpec`).
+ */
+export function expandInput(input, retrievedAtIso) {
+    const source = typeof input.source === "string" ? { name: input.source } : input.source;
+    const license = typeof input.license === "string" ? { name: input.license } : input.license;
+    const dataset = input.dataset == null ? undefined : typeof input.dataset === "string" ? { id: input.dataset } : input.dataset;
+    const { source: _s, license: _l, dataset: _d, retrieved_at: _r, ...rest } = input;
+    return {
+        ...rest,
+        source,
+        license,
+        ...(dataset !== undefined ? { dataset } : {}),
+        retrieved_at: retrievedAtIso,
+    };
+}
+/** Regras semânticas que o zod não cobre por campo isolado. */
+export function assertSemantics(p) {
+    if (p.derived && p.derivation_note === null) {
+        throw new ProvenanceContractError("derived=true exige derivation_note não-nulo (§4 do contrato)");
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/time.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Normalização de timestamps do contrato de proveniência.
+ *
+ * Todo `retrieved_at` (e afins) é serializado em ISO-8601 SEM milissegundos, num fuso
+ * fixo escolhido pelo servidor — o objetivo é a REPRESENTAÇÃO estável (determinismo
+ * byte-a-byte), nunca alterar o instante. Origem do requisito: no senado-br-mcp,
+ * timestamps em UTC faziam respostas noturnas citarem a data do dia seguinte para o
+ * leitor brasileiro; a solução (offset explícito -03:00) é aqui generalizada para
+ * qualquer offset fixo. O fuso do IP do requisitante não serve: em conectores MCP
+ * remotos o IP visto é o do backend do provedor de IA, não o da pessoa.
+ */
+/** Fuso de serialização: "utc" ou offset fixo explícito (ex.: { offset: "-03:00" }). */
+export type TimezoneSpec = "utc" | {
+    offset: string;
+    label?: string;
+};
+/** Converte "-03:00" em minutos (-180). Lança em formato inválido. */
+export declare function parseOffsetMinutes(offset: string): number;
+/** Rótulo humano do fuso, para o rodapé (ex.: "horário de Brasília", "UTC"). */
+export declare function timezoneLabel(tz: TimezoneSpec): string;
+/**
+ * Converte um instante para ISO-8601 canônico no fuso configurado, sem milissegundos
+ * (ex.: "2026-07-14T21:23:45-03:00"; em UTC, sufixo "Z"). Datas puras ("2026-06-28")
+ * e strings não-parseáveis passam inalteradas — nunca corrompe um vintage nem
+ * inventa horário onde não há.
+ */
+export declare function toCanonicalIso(value: string | Date, tz: TimezoneSpec): string;
+//# sourceMappingURL=time.d.ts.map

package/dist/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAKtE,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,GAAG,MAAM,CAGtD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,EAAE,EAAE,YAAY,GAAG,MAAM,CAQ7E"}

package/dist/time.js

@@ -0,0 +1,46 @@
+/**
+ * Normalização de timestamps do contrato de proveniência.
+ *
+ * Todo `retrieved_at` (e afins) é serializado em ISO-8601 SEM milissegundos, num fuso
+ * fixo escolhido pelo servidor — o objetivo é a REPRESENTAÇÃO estável (determinismo
+ * byte-a-byte), nunca alterar o instante. Origem do requisito: no senado-br-mcp,
+ * timestamps em UTC faziam respostas noturnas citarem a data do dia seguinte para o
+ * leitor brasileiro; a solução (offset explícito -03:00) é aqui generalizada para
+ * qualquer offset fixo. O fuso do IP do requisitante não serve: em conectores MCP
+ * remotos o IP visto é o do backend do provedor de IA, não o da pessoa.
+ */
+const OFFSET_RE = /^([+-])(\d{2}):(\d{2})$/;
+const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** Converte "-03:00" em minutos (-180). Lança em formato inválido. */
+export function parseOffsetMinutes(offset) {
+    const m = offset.match(OFFSET_RE);
+    if (!m)
+        throw new Error(`Offset de fuso inválido: "${offset}" (esperado ±HH:MM)`);
+    const sign = m[1] === "-" ? -1 : 1;
+    return sign * (Number(m[2]) * 60 + Number(m[3]));
+}
+/** Rótulo humano do fuso, para o rodapé (ex.: "horário de Brasília", "UTC"). */
+export function timezoneLabel(tz) {
+    if (tz === "utc")
+        return "UTC";
+    return tz.label ?? `UTC${tz.offset}`;
+}
+/**
+ * Converte um instante para ISO-8601 canônico no fuso configurado, sem milissegundos
+ * (ex.: "2026-07-14T21:23:45-03:00"; em UTC, sufixo "Z"). Datas puras ("2026-06-28")
+ * e strings não-parseáveis passam inalteradas — nunca corrompe um vintage nem
+ * inventa horário onde não há.
+ */
+export function toCanonicalIso(value, tz) {
+    if (typeof value === "string" && DATE_ONLY_RE.test(value))
+        return value;
+    const d = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(d.getTime()))
+        return String(value);
+    if (tz === "utc")
+        return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+    const offsetMs = parseOffsetMinutes(tz.offset) * 60_000;
+    const wall = new Date(d.getTime() + offsetMs).toISOString();
+    return wall.replace(/\.\d{3}Z$/, tz.offset);
+}
+//# sourceMappingURL=time.js.map

package/dist/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,SAAS,GAAG,yBAAyB,CAAC;AAC5C,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAE3C,sEAAsE;AACtE,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,qBAAqB,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,EAAgB;IAC5C,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,EAAE,CAAC,KAAK,IAAI,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAoB,EAAE,EAAgB;IACnE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxE,MAAM,CAAC,GAAG,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1D,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,kBAAkB,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC"}

package/docs/contrato-proveniencia-v1.md

@@ -0,0 +1,135 @@
+# Contrato de proveniência do portfólio — v1.0
+
+| Campo | Valor |
+|:--|:--|
+| Status | VIGENTE — implementado por `@sbissoli/mcp-provenance` |
+| Origem | Promoção do contrato v0.1 do ilostat (`ilostat/docs/03-contrato-proveniencia.md`) + envelope nível-1 do senado-br-mcp-cloudflare (`src/utils/provenance.ts`) |
+| Escopo | Toda resposta de toda ferramenta de todo servidor do portfólio (adoção nas Fases 1–4) |
+| Decisões de base | Decisão 5 da Fase 0 (modos `concise`/`detailed`, princípio de linguagem) |
+
+## 1. Princípio
+
+Todo dado retornado por um servidor carrega um **bloco de proveniência determinístico**:
+a mesma consulta, sobre a mesma versão dos dados, produz bloco byte-idêntico exceto pelos
+campos de timestamp. O bloco é o *wedge* do produto — é o que torna cada número citável,
+auditável e reproduzível.
+
+**Determinismo:** serialização canônica — chaves em ordem fixa (a ordem de construção nos
+`render*` da lib é contrato), ausência é `null` explícito, timestamps sem milissegundos em
+fuso fixo configurado por servidor. Os únicos campos que variam entre execuções idênticas
+são `retrieved_at` e citação que embuta data. O determinismo vale **dentro de cada modo**.
+
+**Segregação:** um bloco refere-se a exatamente **uma** fonte. Resposta que combine fontes
+com regimes legais distintos (ex.: CC BY e CC BY-SA) carrega um bloco por fonte, e os
+dados de cada fonte ficam em estruturas separadas, cada qual apontando para seu bloco —
+não contaminar a saída de uma licença com as obrigações da outra. A lib aceita
+`CanonicalProvenance[]` em `result()`/`footer()`; a separação das estruturas de dados é
+responsabilidade do servidor. Para respostas de UMA fonte que fundem **recortes/endpoints**
+diferentes, usar `field_sources` (granularidade por campo), não blocos múltiplos.
+
+## 2. Os dois modos (decisão 5)
+
+- **`concise` (padrão)** — piso legal + citação mínima. Exatamente 6 chaves, nesta ordem:
+  `source`, `source_url`, `data_vintage`, `retrieved_at`, `citation`, `license`
+  (rótulo curto: `license.id` quando existe, senão `license.name`).
+- **`detailed`** — bloco canônico completo (§3). Evals de completude (camada 2) rodam em
+  `detailed` para exercitar os dois caminhos.
+
+O parâmetro técnico que expõe o modo na tool (nome, descrição) é decisão por-servidor e
+vive na descrição da tool — nunca no texto voltado ao leitor.
+
+## 3. Bloco canônico (modo `detailed`)
+
+Ordem fixa de chaves; ausência = `null`:
+
+```jsonc
+{
+  "contract_version": "1.0",
+  "source":   { "name": "...", "agency": null, "database": null, "endpoint": null },
+  "dataset":  { "id": null, "version": null, "name": null },
+  "dimension_key": null,          // objeto {DIM: valor} na ordem das dimensões da fonte
+  "data_vintage": null,           // última atualização segundo a fonte; null se não expõe
+  "retrieved_at": "...",          // ISO-8601 no fuso do servidor — instante REAL da extração
+  "source_url": "...",            // URL canônica que reproduz a consulta
+  "api_version": null,
+  "license":  { "id": null, "name": null, "url": null, "terms_url": null, "verified_at": null },
+  "citation": "...",              // string de citação/atribuição pronta para uso
+  "notices": [],                  // avisos da origem, verbatim
+  "derived": false,
+  "derivation_note": null,        // obrigatório se derived=true
+  "served_from_cache": null,      // true/false quando o servidor distingue; null quando não
+  "field_sources": null           // [{fields, source_url, dataset_id, data_vintage, retrieved_at}]
+}
+```
+
+Invariantes validados server-side (zod + `assertSemantics`), antes de responder:
+`license` exige ao menos `id` ou `name`; `derived=true` exige `derivation_note`.
+
+### Semântica de `retrieved_at`
+
+Instante real da ida ao upstream — preservado pela camada de cache do servidor —, nunca o
+momento do build/deploy. Respostas servidas de cache mantêm o `retrieved_at` do fetch
+original (é a data de extração juridicamente relevante) e podem marcar
+`served_from_cache: true`. O default `new Date()` do builder só é aceitável para
+catálogos estáticos mantidos em código.
+
+### Semântica de `derived`
+
+- `false`: dado bruto, apenas filtrado/paginado/reserializado — atribuição basta.
+- `true`: qualquer transformação de valor (agregação, taxa calculada, interpolação,
+  harmonização). Exige `derivation_note`. Licenças ShareAlike (ex.: UIS CC BY-SA)
+  propagam-se ao derivado — refletir em `license` do bloco.
+- **Caso de fronteira** (conversão de unidade/arredondamento conta como derivação?):
+  decisão **por-servidor**, registrada nos docs do servidor; a lib suporta ambas.
+
+## 4. Mapeamento obrigação legal → campo
+
+| Obrigação típica | Campo que a satisfaz |
+|:--|:--|
+| "credit must be given to …" | `citation` |
+| Reproduzir avisos/disclaimers da origem | `notices` |
+| Marcar obra derivada | `derived` + `derivation_note` |
+| URL completa + data de extração (ex.: UIS) | `citation` (embute ambos) + `source_url` + `retrieved_at` |
+| Registrar licença vigente a cada fetch | `license.verified_at` + log persistente do servidor (fora da lib) |
+
+## 5. Três canais de emissão (`result()`)
+
+1. `structuredContent.provenance` (projeção do modo) + `structuredContent.attribution`
+   (lista canônica de `source_url` distintas, alinhada à RFC `attribution` do MCP,
+   modelcontextprotocol#711) — canal parseável, visível ao modelo.
+2. `_meta` sob chaves namespaced (`{namespace}/provenance`, `{namespace}/attribution`,
+   namespace reverse-DNS por servidor) — out-of-band, auditoria/UI, zero tokens do modelo.
+3. Rodapé de texto compacto no `content` — clientes text-only. Medição no senado: embutir
+   proveniência também no JSON textual custava ~3.8× mais tokens sem benefício.
+
+## 6. Princípio de linguagem (rodapé)
+
+O rodapé fala com o **leitor**; o schema fala com o agente. Registro formal/institucional,
+idioma do servidor, sem jargão técnico nem coloquialidade. Redações fixadas (v1.0):
+
+- **pt-BR**: "A referência completa desta informação pode ser solicitada nesta própria
+  conversa." (redação da decisão 5, fixada)
+- **en**: "The complete reference for this information can be requested here, in this
+  same conversation." (fixada nesta sessão)
+
+O aviso aparece uma única vez por resposta, apenas no modo `concise` — em `detailed` a
+referência completa já está na resposta. Outros idiomas: passar um `LocaleSpec` próprio.
+
+## 7. Mapeamento dos predecessores → v1.0
+
+| Predecessor | Campo antigo | v1.0 |
+|:--|:--|:--|
+| senado nível-1 | `source` (string) | `source.name` |
+| senado nível-1 | `dataset_id` | `dataset.id` |
+| senado nível-1 | `reference_period` | `data_vintage` |
+| senado nível-1 | `citation` | `citation` |
+| senado nível-1 | `license` (string) | `license.name` |
+| senado nível-1 | `field_sources[].reference_period` | `field_sources[].data_vintage` |
+| ilostat v0.1 | `dataflow` (`agency_id`/`dataflow_id`/`version`/`name`) | `dataset` (`id` = dataflow_id; agency já está em `source.agency`) |
+| ilostat v0.1 | `attribution` (string) | `citation` (o nome `attribution` fica reservado à lista de URLs da RFC #711) |
+| ilostat v0.1 | `license.license_verified_at` | `license.verified_at` |
+
+Questões que o v0.1 do ilostat deixava em aberto e o v1.0 resolve: verbosidade → modos da
+decisão 5; `served_from_cache` → campo nullable padrão. Permanecem por-servidor: caso de
+fronteira de `derived` (§3) e confirmações de spike (IDs de dataflow, exposição de
+`data_vintage` pela fonte).

package/docs/diagnostico-adocao-senado-2026-08.md

@@ -0,0 +1,59 @@
+# Diagnóstico de adoção — senado-br-mcp-cloudflare × contrato v1.0
+
+| Campo | Valor |
+|:--|:--|
+| Data | 2026-08-07 (sessão de adoção Fase 1 no senado) |
+| Veredito | **DIVERGENTE — adoção adiada, pendente de decisão do decisor** |
+| Envelope real | `senado-br-mcp-cloudflare/src/utils/provenance.ts` (nível-1, em produção nas 67 tools) |
+| Contrato | `contrato-proveniencia-v1.md` + `@sbissoli/mcp-provenance` (schema/render) |
+
+## Diff — envelope do senado × projeções v1.0
+
+O envelope do senado é **plano** e anterior aos modos `concise`/`detailed`. Não é
+byte-igual a nenhuma das duas projeções:
+
+| Envelope senado (atual) | v1.0 `concise` | v1.0 `detailed` |
+|:--|:--|:--|
+| `source` (string) | `source` (string = `source.name`) — igual | `source` vira **objeto** `{name, agency, database, endpoint}` |
+| `source_url` | igual | igual (posição diferente na ordem fixa) |
+| `dataset_id?` (omitido quando ausente) | **não existe** (cai fora do bloco) | `dataset.id` (objeto `{id, version, name}`, nulls explícitos) |
+| `reference_period?` | **renomeado** `data_vintage`, `null` explícito | idem |
+| `retrieved_at` | igual | igual |
+| `citation` | igual | igual |
+| `license?` (string, omitida quando ausente) | `license` (rótulo curto, `null` explícito) | `license` vira **objeto** `{id, name, url, terms_url, verified_at}` |
+| `api_version?` | **não existe** | `api_version` (null explícito) |
+| `field_sources?[].reference_period` | **não existe** | `field_sources[].data_vintage` (+ nulls explícitos) |
+| — | — | campos novos: `contract_version`, `dimension_key`, `notices`, `derived`, `derivation_note`, `served_from_cache` |
+
+Diferenças transversais:
+
+1. **Renome de chave lida pelo modelo**: `reference_period` → `data_vintage` (e dentro de
+   `field_sources`). Muda a resposta de todas as 67 tools.
+2. **Ausência**: senado omite campos opcionais; v1.0 exige `null` explícito em ordem fixa
+   de chaves (determinismo é contrato).
+3. **Sem modos**: o senado emite um único envelope; v1.0 define `concise` (6 chaves) ×
+   `detailed` (bloco canônico) com parâmetro por-servidor.
+4. **`license` string × objeto**: no `concise` o rótulo curto coincide com a string atual
+   do senado, mas no canônico é objeto com piso legal (`id` ou `name`).
+5. **Rodapé**: v1.0 fixa a redação "A referência completa desta informação pode ser
+   solicitada nesta própria conversa." (decisão 5); o rodapé atual do senado é
+   `Fonte: X · url · extraído em … · competência …` — também mudaria.
+
+## Consequência
+
+A adoção **não é troca de import**: altera chaves/shape do `structuredContent.provenance`,
+do espelho em `_meta` e do rodapé de texto de **todas as 67 tools** — exatamente a classe
+de mudança que o harness de evals e o widget do ChatGPT App leem. Conforme o plano da
+sessão (ADOCAO_SENADO_PROMPT_SESSAO.md, escopo 3): não adotar em silêncio.
+
+## Decisão pendente (decisor)
+
+- **Opção A**: release menor dedicado do senado (bump de versão + nota no README) que
+  migra o envelope ao v1.0 (modo `concise` como padrão preserva o "peso" atual da
+  resposta; `reference_period`→`data_vintage` é a única quebra visível no modo padrão,
+  além dos nulls explícitos e da perda de `dataset_id`/`api_version` no bloco padrão).
+- **Opção B**: adiar para a fase do congresso-br (primeiro servidor novo a nascer já no
+  v1.0), mantendo o senado no envelope nível-1 até lá.
+
+A adoção de `@sbissoli/mcp-stats` e `@sbissoli/mcp-evals` no senado **não depende** desta
+decisão (concluída em 2026-08-07).

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@sbissoli/mcp-provenance",
+  "version": "0.1.0",
+  "description": "Contrato de proveniência para servidores MCP: todo retorno de tool carrega fonte, endpoint, período, data de extração e licença, em dois modos (concise/detailed), com serialização determinística",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "provenance",
+    "data-provenance",
+    "open-data",
+    "attribution"
+  ],
+  "author": "Sidney Bissoli <sbissoli76@gmail.com>",
+  "license": "MIT"
+}