cloudbroker-sdk 0.7.0 → 0.8.0

package/.github/workflows/publish.yml

@@ -1,6 +1,12 @@
 name: Publish to npm
 
 on:
+  # Testar também em PR: até aqui a suíte só rodava no caminho de publish, e
+  # publish só dispara em push no main que toque package.json. Ou seja, um PR
+  # que quebrasse o SDK não era pego por nada — o erro só apareceria na hora
+  # de lançar a versão. Mesmo formato adotado no backend (job `test` rodando
+  # em PR e push, com o job de entrega dependendo dele).
+  pull_request:
   push:
     branches: [main]
     paths:
@@ -16,31 +22,100 @@ on:
   workflow_dispatch:
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      # Não falha as demais versões quando uma quebra — saber que 24 passa e
+      # 20 não é a informação útil; abortar em cima da primeira esconde isso.
+      fail-fast: false
+      matrix:
+        # Este pacote roda DENTRO da aplicação de produção do cliente, então o
+        # que importa não é "o Node que a gente gosta", é a faixa que o cliente
+        # pode estar rodando.
+        #
+        # 20 é o piso: era a única versão testada até aqui, e sair dela sem
+        # aviso quebraria quem ainda está lá. Está EOL desde março/2026, e é
+        # exatamente por isso que ele não pode ser a ÚNICA — testar só nele
+        # significava nunca exercitar o SDK no Node que os clientes usam hoje.
+        node: [20, 22, 24]
+    name: test (node ${{ matrix.node }})
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Instalar dependências
+        run: npm ci || npm install
+
+      - name: Rodar testes
+        run: npm test
+
   publish:
+    needs: test
+    # Só publica no caminho de release. Sem esta guarda, o gatilho de
+    # pull_request acima tentaria publicar a cada PR.
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     permissions:
       contents: read
       id-token: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
-          node-version: 20
+          # LTS atual para o artefato publicado. A compatibilidade com as
+          # outras versões é garantida pela matriz do job `test` acima, que
+          # este job exige via `needs`.
+          node-version: 22
           registry-url: 'https://registry.npmjs.org'
 
-      # Gate de teste antes do publish — este pacote roda DENTRO da aplicação
-      # de produção do cliente; publicar sem rodar a suíte já era um risco
-      # aberto (nenhum CI de teste existia neste repo).
-      - name: Instalar dependências de teste
+      - name: Instalar dependências
         run: npm ci || npm install
 
-      - name: Rodar testes
-        run: npm test
+      # Trusted Publishing (OIDC): o npm confia neste workflow pelo token de
+      # identidade do GitHub (permissions.id-token: write acima) — sem NPM_TOKEN
+      # de longa duração. O publish por token falhava com EOTP desde 27/07
+      # (token que exige 2FA), e as versões saíam à mão, pulando a suíte.
+      # Exige npm >= 11.5.1; o Node 22 traz 10.x, e com npm antigo o publish
+      # falha sem dizer por quê. Versão fixa, a mesma do cloudbroker-mcp.
+      # Configuração do lado do npm (uma vez, pelo dono do pacote):
+      #   npm trust github cloudbroker-sdk --file publish.yml \
+      #     --repo cloudbroker-app/cloudbroker-sdk --allow-stage-publish
+      # O gatilho dispara em QUALQUER mudança no package.json, não só em troca
+      # de versão — o merge do PR #17 (só o campo `repository`) tentou
+      # republicar a 0.7.0 e deixou o main vermelho. Se a versão já está no
+      # registro, encerra com aviso. Só pula com confirmação positiva (o npm
+      # devolveu exatamente esta versão): 404 ou falha de rede seguem para o
+      # publish, que falha alto se houver problema de verdade.
+      - name: Versão já publicada?
+        id: published
+        run: |
+          NAME=$(node -p "require('./package.json').name")
+          VERSION=$(node -p "require('./package.json').version")
+          FOUND=$(npm view "$NAME@$VERSION" version 2>/dev/null || true)
+          if [ "$FOUND" = "$VERSION" ]; then
+            echo "::notice::$NAME@$VERSION já está no npm — nada a publicar (troque a versão para lançar)."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Atualizar npm (OIDC exige >= 11.5.1; npm stage vem no 11.19)
+        if: steps.published.outputs.skip != 'true'
+        run: npm install -g npm@11.19.1 && npm --version
 
-      - name: Publish to npm
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      # Staged publishing: o CI só deixa a versão em STAGING (fora do ar); quem
+      # publica de fato é uma pessoa, com 2FA:
+      #   npm stage list cloudbroker-sdk
+      #   npm stage approve <id-do-staging>
+      # Sem NODE_AUTH_TOKEN: a autenticação vem do OIDC.
+      - name: Stage no npm (aprovação manual com 2FA)
+        if: steps.published.outputs.skip != 'true'
+        run: npm stage publish

package/README.md

@@ -309,6 +309,46 @@ app.use(CloudBrokerCloud.expressMiddleware({
 Prioridade de cada campo: explícito no `.send()` (`cbLabel`/`cbProduct`/`cbTeam`) >
 contexto do middleware > valor estático do `wrapAWS` > `null`.
 
+### Custo por execução e versão do código (0.8.0)
+
+Cada evento do `wrapAWS`/`wrapAzure` é uma **chamada de API**, não uma
+**execução** do trecho. Se o custo de um trecho sobe, só com chamadas não dá
+para saber se o código passou a chamar mais ou se veio mais tráfego. O
+`ExecutionCounter` conta as execuções e fecha essa conta: **custo por
+execução** e **chamadas por execução**.
+
+```js
+import { CloudBrokerCloud, ExecutionCounter } from "cloudbroker-sdk";
+
+const execucoes = new ExecutionCounter({ apiKey: process.env.CLOUDBROKER_API_KEY });
+
+app.use(CloudBrokerCloud.expressMiddleware({
+  product: "checkout",
+  label:   (req) => req.path.split("/").slice(0, 3).join("/"),         // prefixo da rota ("/api/pedidos"), sem ids
+  executions: execucoes,                                               // 1 execução por requisição
+}));
+
+// Fora do Express (jobs, filas, workers):
+await CloudBrokerCloud.trackExecution("job:fechamento-mensal", () => fecharMes(), {
+  product: "financeiro", executions: execucoes,
+});
+```
+
+- A contagem fica em memória, agregada por trecho, app, versão e hora, e sai
+  em lote a cada 60 s (`flushIntervalMs`). Nada de rede no caminho da
+  requisição; o timer não segura o processo.
+- **Use rótulo de baixa cardinalidade.** Um rótulo com id (`/api/pedidos/123`)
+  cria uma combinação por pedido; acima de 200 combinações pendentes o
+  excedente é descartado e somado em `execucoes.dropped`. O rótulo padrão do
+  middleware é o caminho cru — com `executions`, passe sempre um `label`.
+  (Middleware de `app.use` roda antes do roteamento: `req.route` ainda não
+  existe nele.)
+- **Versão do código:** defina `CLOUDBROKER_VERSION` (ex.: o `GIT_SHA` do
+  build) ou passe `version` ao `ExecutionCounter` e ao `wrapAWS`/`wrapAzure`.
+  Ela vai nas execuções e nas chamadas, para comparar o trecho antes e depois
+  de um deploy pela versão que de fato rodou.
+- No shutdown: `await execucoes.flush(); execucoes.stop();`.
+
 ## Garantias
 
 - **Fire-and-forget**: se o CloudBroker estiver fora, sua aplicação não é afetada

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "cloudbroker-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "CloudBroker SDK — Token Intelligence & Operational Financial Intelligence",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudbroker-app/cloudbroker-sdk.git"
+  },
   "main": "src/index.js",
   "type": "module",
   "exports": {
     ".": "./src/index.js"
   },
   "scripts": {
-    "test": "node src/test.js && node src/test-azure-real.js && node src/test-gemini-real.js"
+    "test": "node src/test.js && node src/test-executions.js && node src/test-azure-real.js && node src/test-gemini-real.js"
   },
   "keywords": [
     "cloudbroker",

package/src/client.js

@@ -48,7 +48,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.7.0",
+        sdkVersion: "0.8.0",
         sentAt: new Date().toISOString(),
       };
       if (this.#cloudQueue.length < MAX_QUEUE_SIZE) {
@@ -104,7 +104,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.7.0",
+        sdkVersion: "0.8.0",
         sentAt: new Date().toISOString(),
       };
 

package/src/cloud-wrapper.js

@@ -36,6 +36,7 @@ import {
   AZURE_COSMOS_ITEMS_ITERATOR_OPS,
 } from "./pricing-cloud.js";
 import { cbStore } from "./context.js";
+import { resolveVersion } from "./executions.js";
 
 // Nomes de construtor do @azure/* → tipo do nó na cadeia de sub-clients.
 const AZURE_BLOB_KIND = {
@@ -149,10 +150,12 @@ export class CloudBrokerCloud {
    * @param {string} [options.team]    — nome do squad (ex: "mobile")
    * @param {string} [options.region="us-east-2"]
    * @param {string} [options.endpoint] — endpoint de eventos de nuvem (opcional)
+   * @param {string} [options.version] — versão do código (padrão: env CLOUDBROKER_VERSION, ex.: o GIT_SHA do build)
    * @param {boolean} [options.debug=false]
    */
   static wrapAWS(client, options = {}) {
     const { apiKey, product, team, region = "us-east-2", endpoint, debug = false } = options;
+    const version = resolveVersion(options.version);
     if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
 
     if (!client || typeof client.send !== "function") {
@@ -200,6 +203,7 @@ export class CloudBrokerCloud {
           billingUnit,
           latencyMs: Date.now() - start,
           region:    clientRegion,
+          version,
         });
       } catch (err) {
         if (debug) console.warn("[CloudBroker] trackCloud error:", err.message);
@@ -221,6 +225,9 @@ export class CloudBrokerCloud {
    * @param {string|((req)=>string)} [options.label]   — trecho (default: "MÉTODO /caminho")
    * @param {string|((req)=>string)} [options.product] — App (sobrescreve o product do wrapAWS)
    * @param {string|((req)=>string)} [options.team]    — Grupo (sobrescreve o team do wrapAWS)
+   * @param {import("./executions.js").ExecutionCounter} [options.executions] — se informado,
+   *   conta UMA execução do trecho por requisição (custo por execução, Passo 2).
+   *   Use rótulo de baixa cardinalidade (módulo/rota com padrão), nunca o caminho cru com ids.
    * @returns {(req,res,next)=>void}
    */
   static expressMiddleware(options = {}) {
@@ -232,12 +239,38 @@ export class CloudBrokerCloud {
     const resolveProduct = mk(options.product, () => undefined);
     const resolveTeam    = mk(options.team, () => undefined);
 
+    const executions = options.executions;
+
     return (req, res, next) => {
       const safe = (fn) => { try { return fn(req); } catch { return undefined; } };
-      cbStore.run({ label: safe(resolveLabel), product: safe(resolveProduct), team: safe(resolveTeam) }, () => next());
+      const ctx = { label: safe(resolveLabel), product: safe(resolveProduct), team: safe(resolveTeam) };
+      try {
+        if (executions && typeof executions.count === "function") executions.count(ctx);
+      } catch { /* contador nunca derruba a requisição */ }
+      cbStore.run(ctx, () => next());
     };
   }
 
+  /**
+   * Roda `fn` como UMA execução do trecho `label`, para código fora do
+   * Express (jobs, filas, workers): as chamadas de nuvem/IA feitas dentro de
+   * `fn` herdam o trecho (mesmo contexto do expressMiddleware) e, com
+   * `options.executions`, a execução é contada. Devolve o que `fn` devolver
+   * (inclusive a Promise) e propaga o erro de `fn` — a instrumentação em si
+   * nunca lança.
+   *
+   * @param {string} label — trecho (baixa cardinalidade, ex.: "job:fechamento")
+   * @param {Function} fn
+   * @param {{product?: string, team?: string, executions?: import("./executions.js").ExecutionCounter}} [options]
+   */
+  static trackExecution(label, fn, options = {}) {
+    const ctx = { label, product: options.product, team: options.team };
+    try {
+      if (options.executions && typeof options.executions.count === "function") options.executions.count(ctx);
+    } catch { /* contador nunca derruba a execução */ }
+    return cbStore.run(ctx, fn);
+  }
+
   /**
    * Envolve um client do Azure SDK (Blob Storage / Cosmos DB) e rastreia cada
    * chamada de data-plane como evento de custo — mesmo contrato do wrapAWS.
@@ -272,6 +305,7 @@ export class CloudBrokerCloud {
    */
   static wrapAzure(client, options = {}) {
     const { apiKey, product, team, region = "eastus2", endpoint, debug = false } = options;
+    const version = resolveVersion(options.version);
     if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
 
     const name = client?.constructor?.name || "";
@@ -295,7 +329,7 @@ export class CloudBrokerCloud {
     }
 
     const cb  = new CloudBrokerClient({ apiKey, cloudEndpoint: endpoint, debug });
-    const env = { cb, product, team, region, debug };
+    const env = { cb, product, team, region, debug, version };
     return blobKind
       ? CloudBrokerCloud.#wrapBlobNode(client, env)
       : CloudBrokerCloud.#wrapCosmosNode(client, env, cosmosKind);
@@ -348,6 +382,7 @@ export class CloudBrokerCloud {
         billingUnit,
         latencyMs,
         region:    env.region,
+        version:   env.version,
       });
     } catch (err) {
       if (env.debug) console.warn("[CloudBroker] trackCloud error:", err.message);

package/src/executions.js

@@ -0,0 +1,152 @@
+/**
+ * ExecutionCounter — contador de EXECUÇÕES de trecho de código (0.8.0).
+ *
+ * Por que existe: o wrapAWS/wrapAzure grava um evento por CHAMADA de API, não
+ * por execução do trecho. Sem o número de execuções, "o código passou a chamar
+ * mais" e "veio mais tráfego" são indistinguíveis — o custo por chamada é
+ * quase constante por construção. Este contador é o denominador que separa os
+ * dois (custo por execução, chamadas por execução).
+ *
+ * Como: contagem EM MEMÓRIA, agregada por (trecho, app, versão, hora UTC), e
+ * enviada em lote a cada `flushIntervalMs` para POST /api/cloud/executions.
+ * Uma requisição = uma soma num Map; nada de rede no caminho da aplicação.
+ *
+ * Garantias (iguais às do resto do SDK):
+ *   • nunca lança para a aplicação do cliente;
+ *   • timer com `.unref()` — não segura o processo (Lambda, cron, CLI);
+ *   • memória limitada: no máximo `maxKeys` combinações pendentes; o excedente
+ *     é descartado e contado em `dropped` (rótulo de alta cardinalidade, como
+ *     uma rota com id no caminho, não pode crescer sem limite);
+ *   • contagem com mais de 7 dias sem conseguir enviar é descartada (o backend
+ *     recusa, e reenviar para sempre seria inútil).
+ *
+ * Uso:
+ *   const execucoes = new ExecutionCounter({ apiKey: "cb-key-xxx" }); // version ← CLOUDBROKER_VERSION
+ *   app.use(CloudBrokerCloud.expressMiddleware({ label: ..., executions: execucoes }));
+ *   await CloudBrokerCloud.trackExecution("job:fechamento", () => fecharMes(), { executions: execucoes });
+ */
+
+const DEFAULT_EXECUTIONS_ENDPOINT = "https://api.cloudbroker.app.br/api/cloud/executions";
+const HOUR_MS = 3_600_000;
+const MAX_AGE_MS = 7 * 24 * HOUR_MS;
+
+/** Versão do código do cliente: explícita > CLOUDBROKER_VERSION > null. */
+export function resolveVersion(explicit) {
+  const v = typeof explicit === "string" && explicit.trim() ? explicit
+    : (typeof process !== "undefined" ? process.env?.CLOUDBROKER_VERSION : undefined);
+  return typeof v === "string" && v.trim() ? v.trim().slice(0, 64) : null;
+}
+
+function hourStartIso(ms) {
+  return new Date(Math.floor(ms / HOUR_MS) * HOUR_MS).toISOString();
+}
+
+export class ExecutionCounter {
+  #apiKey;
+  #endpoint;
+  #version;
+  #debug;
+  #maxKeys;
+  #now;
+  #pending = new Map();
+  #flushing = false;
+  #timer = null;
+  dropped = 0;
+
+  /**
+   * @param {object} options
+   * @param {string} options.apiKey — API key CloudBroker do tipo SDK
+   * @param {string} [options.version] — versão do código (padrão: CLOUDBROKER_VERSION)
+   * @param {string} [options.endpoint]
+   * @param {number} [options.flushIntervalMs=60000]
+   * @param {number} [options.maxKeys=200] — o backend recusa lote com mais de 200
+   * @param {boolean} [options.debug=false]
+   */
+  constructor({ apiKey, version, endpoint = DEFAULT_EXECUTIONS_ENDPOINT, flushIntervalMs = 60_000, maxKeys = 200, debug = false, now } = {}) {
+    if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
+    this.#apiKey = apiKey;
+    this.#endpoint = endpoint;
+    this.#version = resolveVersion(version);
+    this.#debug = debug;
+    this.#maxKeys = Math.max(1, Math.min(200, Math.floor(maxKeys) || 200));
+    this.#now = typeof now === "function" ? now : Date.now;
+    if (flushIntervalMs > 0) {
+      this.#timer = setInterval(() => { this.flush(); }, flushIntervalMs);
+      if (typeof this.#timer?.unref === "function") this.#timer.unref();
+    }
+  }
+
+  /** Versão que este contador anexa às execuções. */
+  get version() { return this.#version; }
+
+  /** Combinações pendentes de envio (para diagnóstico/teste). */
+  get pendingKeys() { return this.#pending.size; }
+
+  /**
+   * Soma uma execução do trecho. Nunca lança.
+   * @param {{label?: string, product?: string}} ctx
+   */
+  count(ctx) {
+    try {
+      const label = ctx?.label, product = ctx?.product;
+      if (typeof label !== "string" || !label.trim()) return;
+      const hour = hourStartIso(this.#now());
+      const prod = typeof product === "string" && product.trim() ? product : null;
+      const key = `${hour}\u0000${label}\u0000${prod || ""}`;
+      const cur = this.#pending.get(key);
+      if (cur) { cur.count++; return; }
+      if (this.#pending.size >= this.#maxKeys) { this.dropped++; return; }
+      this.#pending.set(key, { label, product: prod, version: this.#version, hour, count: 1 });
+    } catch (err) {
+      if (this.#debug) console.warn("[CloudBroker] executions.count error:", err.message);
+    }
+  }
+
+  /** Envia o pendente. Nunca lança; em falha transitória, a contagem volta para a fila. */
+  async flush() {
+    if (this.#flushing || this.#pending.size === 0) return;
+    this.#flushing = true;
+    const batch = [...this.#pending.values()];
+    this.#pending = new Map();
+    let devolver = false;
+    try {
+      const res = await fetch(this.#endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "x-cloudbroker-key": this.#apiKey },
+        body: JSON.stringify({ executions: batch }),
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!res.ok) {
+        // 4xx (exceto 429) é recusa definitiva — reenviar o mesmo lote não muda nada.
+        devolver = res.status === 429 || res.status >= 500;
+        if (this.#debug) console.warn(`[CloudBroker] executions flush failed: ${res.status}${devolver ? " (vai tentar de novo)" : " (descartado)"}`);
+      } else if (this.#debug) {
+        console.log(`[CloudBroker] flushed ${batch.length} execution buckets`);
+      }
+    } catch (err) {
+      devolver = true;
+      if (this.#debug) console.warn("[CloudBroker] executions flush error:", err.message);
+    } finally {
+      if (devolver) this.#requeue(batch);
+      this.#flushing = false;
+    }
+  }
+
+  #requeue(batch) {
+    const limite = this.#now() - MAX_AGE_MS;
+    for (const it of batch) {
+      if (Date.parse(it.hour) < limite) { this.dropped += it.count; continue; }
+      const key = `${it.hour}\u0000${it.label}\u0000${it.product || ""}`;
+      const cur = this.#pending.get(key);
+      if (cur) cur.count += it.count;
+      else if (this.#pending.size < this.#maxKeys) this.#pending.set(key, it);
+      else this.dropped += it.count;
+    }
+  }
+
+  /** Para o timer (ex.: no shutdown, depois de um `await flush()`). */
+  stop() {
+    if (this.#timer) clearInterval(this.#timer);
+    this.#timer = null;
+  }
+}

package/src/index.js

@@ -10,4 +10,5 @@
 export { CloudBrokerAI } from "./wrapper.js";
 export { CloudBrokerCloud } from "./cloud-wrapper.js";
 export { CloudBrokerClient } from "./client.js";
+export { ExecutionCounter } from "./executions.js";
 export { estimateCloudCost, CLOUD_PRICING } from "./pricing-cloud.js";

package/src/test-executions.js

@@ -0,0 +1,190 @@
+/**
+ * Contador de execuções (0.8.0). Execute: node src/test-executions.js
+ * Sem rede: fetch é substituído por um falso que registra o que seria enviado.
+ */
+import assert from "node:assert";
+import { readFileSync } from "node:fs";
+import { ExecutionCounter, resolveVersion } from "./executions.js";
+import { CloudBrokerCloud } from "./cloud-wrapper.js";
+import { cbStore } from "./context.js";
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log("✅", msg); };
+
+const realFetch = globalThis.fetch;
+const sent = [];
+let respond = () => ({ ok: true, status: 200 });
+globalThis.fetch = async (url, opts) => {
+  sent.push({ url, headers: opts.headers, body: JSON.parse(opts.body) });
+  const r = respond();
+  if (r instanceof Error) throw r;
+  return r;
+};
+
+const T0 = Date.parse("2026-10-12T15:42:10.000Z");
+let clock = T0;
+const mk = (o = {}) => new ExecutionCounter({ apiKey: "cb-test", flushIntervalMs: 0, now: () => clock, ...o });
+
+// ─── versão ──────────────────────────────────────────────────────────────────
+delete process.env.CLOUDBROKER_VERSION;
+ok(resolveVersion() === null, "sem versão e sem env → null (nunca inventa versão)");
+process.env.CLOUDBROKER_VERSION = " abc1234 ";
+ok(resolveVersion() === "abc1234", "versão vem de CLOUDBROKER_VERSION, sem espaços");
+ok(resolveVersion("v2") === "v2", "versão explícita vence o env");
+ok(resolveVersion("x".repeat(100)).length === 64, "versão com teto de 64");
+
+// ─── agregação ───────────────────────────────────────────────────────────────
+{
+  const c = mk();
+  c.count({ label: "checkout", product: "Loja" });
+  c.count({ label: "checkout", product: "Loja" });
+  c.count({ label: "checkout", product: "Loja" });
+  c.count({ label: "checkout", product: "Outro" });
+  ok(c.pendingKeys === 2, "mesmo trecho+app+hora vira 1 combinação; app diferente, outra");
+  c.count({ label: "" }); c.count({}); c.count(null); c.count({ label: 42 });
+  ok(c.pendingKeys === 2, "sem rótulo não conta e não lança");
+  await c.flush();
+  const body = sent.at(-1).body.executions;
+  const loja = body.find((e) => e.product === "Loja");
+  ok(loja.count === 3 && loja.hour === "2026-10-12T15:00:00.000Z" && loja.version === "abc1234", "lote enviado: contagem somada, início da hora em UTC, versão anexada");
+  ok(sent.at(-1).url.endsWith("/api/cloud/executions") && sent.at(-1).headers["x-cloudbroker-key"] === "cb-test", "endpoint e cabeçalho da key");
+  ok(c.pendingKeys === 0, "enviado com sucesso → fila vazia");
+
+  clock = T0 + 3_600_000;
+  c.count({ label: "checkout", product: "Loja" });
+  clock = T0;
+  c.count({ label: "checkout", product: "Loja" });
+  ok(c.pendingKeys === 2, "horas diferentes são combinações diferentes");
+}
+
+// ─── teto de memória ─────────────────────────────────────────────────────────
+{
+  const c = mk({ maxKeys: 3 });
+  for (let i = 0; i < 5; i++) c.count({ label: `/api/apps/${i}` });
+  c.count({ label: "/api/apps/0" });
+  ok(c.pendingKeys === 3 && c.dropped === 2, "acima do teto de combinações descarta e conta em dropped (rótulo com id não cresce sem limite)");
+  const big = mk({ maxKeys: 5000 });
+  for (let i = 0; i < 250; i++) big.count({ label: `t${i}` });
+  ok(big.pendingKeys === 200 && big.dropped === 50, "maxKeys efetivo nunca passa de 200");
+}
+
+// ─── falha de envio ──────────────────────────────────────────────────────────
+{
+  const c = mk();
+  c.count({ label: "a" }); c.count({ label: "a" });
+  respond = () => new Error("ECONNRESET");
+  await c.flush();
+  ok(c.pendingKeys === 1, "erro de rede → a contagem volta para a fila");
+  c.count({ label: "a" });
+  respond = () => ({ ok: false, status: 503 });
+  await c.flush();
+  respond = () => ({ ok: true, status: 200 });
+  await c.flush();
+  ok(sent.at(-1).body.executions[0].count === 3, "503 também volta para a fila, e a contagem não se perde nem duplica");
+
+  c.count({ label: "b" });
+  respond = () => ({ ok: false, status: 400 });
+  await c.flush();
+  ok(c.pendingKeys === 0, "4xx é recusa definitiva → descartado, sem reenviar para sempre");
+  respond = () => ({ ok: false, status: 429 });
+  c.count({ label: "b" });
+  await c.flush();
+  ok(c.pendingKeys === 1, "429 volta para a fila");
+  respond = () => ({ ok: true, status: 200 });
+
+  const velho = mk();
+  velho.count({ label: "v" });
+  respond = () => new Error("offline");
+  clock = T0 + 8 * 24 * 3_600_000; // o flush falha 8 dias depois
+  await velho.flush();
+  clock = T0;
+  respond = () => ({ ok: true, status: 200 });
+  ok(velho.pendingKeys === 0 && velho.dropped === 1, "contagem com mais de 7 dias não volta para a fila (o backend recusaria)");
+}
+
+// ─── nunca lança, e não segura o processo ────────────────────────────────────
+{
+  // Timer padrão (60s) SEM stop(): um processo filho precisa terminar sozinho.
+  // Sem o .unref(), o timer seguraria o event loop e o filho não sairia.
+  const { spawnSync } = await import("node:child_process");
+  const filho = spawnSync(process.execPath, ["--input-type=module", "-e",
+    `import { ExecutionCounter } from ${JSON.stringify(new URL("./executions.js", import.meta.url).href)};
+     const c = new ExecutionCounter({ apiKey: "cb-test" }); c.count({ label: "x" });`], { timeout: 10_000 });
+  ok(filho.status === 0 && !filho.error, "o timer do contador não segura o processo (Lambda, cron, CLI terminam sozinhos)");
+
+  const c = mk();
+  respond = () => { throw new TypeError("fetch quebrado"); };
+  c.count({ label: "x" });
+  await c.flush();
+  respond = () => ({ ok: true, status: 200 });
+  ok(true, "fetch que lança não escapa do flush");
+  c.stop();
+  assert.throws(() => new ExecutionCounter({}), /apiKey/);
+  ok(true, "sem apiKey lança na construção (erro de configuração, não de execução)");
+}
+
+// ─── expressMiddleware ───────────────────────────────────────────────────────
+{
+  const c = mk();
+  const mw = CloudBrokerCloud.expressMiddleware({ label: (req) => `mod:${req.path}`, product: "Loja", executions: c });
+  let vistoNoContexto;
+  await new Promise((r) => mw({ method: "GET", path: "/x" }, {}, () => { vistoNoContexto = cbStore.getStore(); r(); }));
+  await new Promise((r) => mw({ method: "GET", path: "/x" }, {}, r));
+  await c.flush();
+  const ex = sent.at(-1).body.executions;
+  ok(ex.length === 1 && ex[0].label === "mod:/x" && ex[0].product === "Loja" && ex[0].count === 2, "uma execução por requisição, com o mesmo trecho/app do contexto");
+  ok(vistoNoContexto?.label === "mod:/x", "o contexto continua chegando ao handler");
+
+  const quebrado = { count() { throw new Error("boom"); } };
+  const mw2 = CloudBrokerCloud.expressMiddleware({ label: "a", executions: quebrado });
+  let passou = false;
+  mw2({ method: "GET", path: "/" }, {}, () => { passou = true; });
+  ok(passou, "contador que lança não derruba a requisição (next é chamado)");
+  const mw3 = CloudBrokerCloud.expressMiddleware({ label: "a" });
+  let chamou = false;
+  mw3({ method: "GET", path: "/" }, {}, () => { chamou = true; });
+  ok(chamou, "sem `executions`, o middleware se comporta como antes");
+}
+
+// ─── trackExecution ──────────────────────────────────────────────────────────
+{
+  const c = mk();
+  const r1 = CloudBrokerCloud.trackExecution("job:fechamento", () => cbStore.getStore().label, { executions: c, product: "Financeiro" });
+  ok(r1 === "job:fechamento", "fn roda dentro do contexto do trecho e o retorno é devolvido");
+  const r2 = await CloudBrokerCloud.trackExecution("job:fechamento", async () => 7, { executions: c, product: "Financeiro" });
+  ok(r2 === 7, "fn assíncrona: devolve a Promise");
+  let erro;
+  try { await CloudBrokerCloud.trackExecution("job:fechamento", async () => { throw new Error("falha do job"); }, { executions: c, product: "Financeiro" }); } catch (e) { erro = e; }
+  ok(erro?.message === "falha do job", "erro de fn propaga intacto (a instrumentação não o engole)");
+  await c.flush();
+  ok(sent.at(-1).body.executions[0].count === 3, "cada chamada conta uma execução (inclusive a que falhou)");
+  ok(CloudBrokerCloud.trackExecution("x", () => 1, { executions: { count() { throw new Error("x"); } } }) === 1, "contador que lança não derruba a execução");
+  ok(CloudBrokerCloud.trackExecution("x", () => 2) === 2, "sem contador funciona só como contexto");
+}
+
+// ─── versão nos eventos de chamada ───────────────────────────────────────────
+{
+  process.env.CLOUDBROKER_VERSION = "abc1234";
+  class S3Client { constructor() { this.config = { region: async () => "us-east-2" }; } async send() { return {}; } }
+  class GetObjectCommand { constructor(input) { this.input = input; } }
+  const s3 = CloudBrokerCloud.wrapAWS(new S3Client(), { apiKey: "cb-test" });
+  await s3.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
+  await new Promise((r) => setTimeout(r, 30));
+  const ev = sent.filter((s) => s.url.endsWith("/api/cloud/events")).at(-1)?.body.events[0];
+  ok(ev?.version === "abc1234", `evento de chamada leva a versão do código (veio ${ev?.version})`);
+  const s3b = CloudBrokerCloud.wrapAWS(new S3Client(), { apiKey: "cb-test", version: "v9" });
+  await s3b.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
+  await new Promise((r) => setTimeout(r, 30));
+  ok(sent.filter((s) => s.url.endsWith("/api/cloud/events")).at(-1)?.body.events[0].version === "v9", "versão explícita do wrapAWS vence o env");
+}
+
+// ─── versão do pacote ────────────────────────────────────────────────────────
+{
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  const client = readFileSync(new URL("./client.js", import.meta.url), "utf8");
+  const declaradas = [...client.matchAll(/sdkVersion:\s*"([^"]+)"/g)].map((m) => m[1]);
+  ok(declaradas.length > 0 && declaradas.every((v) => v === pkg.version), `sdkVersion dos eventos (${declaradas.join(", ")}) = versão do package.json (${pkg.version})`);
+}
+
+globalThis.fetch = realFetch;
+console.log(`\n🎉 ${pass} asserções passaram.`);