cloudbroker-sdk 0.8.1 → 0.9.0

package/README.md

@@ -349,6 +349,29 @@ await CloudBrokerCloud.trackExecution("job:fechamento-mensal", () => fecharMes()
   de um deploy pela versão que de fato rodou.
 - No shutdown: `await execucoes.flush(); execucoes.stop();`.
 
+### Custo por operação (0.9.0)
+
+Cada execução ganha um `operationId` (`op_` + UUID v7, gerado localmente). As chamadas de nuvem e de IA feitas durante a execução levam esse id, e o CloudBroker passa a somar o custo de **uma** execução (ex.: S3 + DynamoDB + OpenAI de um `POST /checkout`).
+
+- `expressMiddleware` abre uma operação por requisição, e `trackExecution`, uma por execução. Quem já usa um dos dois não precisa mudar nada.
+- Para jobs, filas e operações de negócio:
+
+```js
+import { CloudBroker } from "cloudbroker-sdk";
+
+await CloudBroker.operation("process-order", { product: "commerce", team: "checkout" }, async () => {
+  await s3.send(new PutObjectCommand({ ... }));          // herda o operationId
+  await openai.chat.completions.create({ ... });           // idem
+});
+```
+
+- **Aninhamento:** uma operação aberta dentro de outra recebe id próprio e `parentOperationId`. Cada evento conta só para a operação mais interna, então a soma não conta nada duas vezes.
+- **Nome:** use nome de baixa cardinalidade (`"GET /users/:id"`, nunca `"/users/123"`). O nome da operação vira o trecho (`label`).
+- **Escrita:** nenhum evento de início ou fim de operação é enviado. O custo da operação é a soma dos eventos que o SDK já manda.
+- **Fora desta versão:** `tenantId` (o tenant é sempre o da API key), `customerId` e `metadata` (risco de dado pessoal).
+- `CloudBroker.currentOperation()` devolve os ids da operação corrente, para correlacionar com o log da aplicação.
+- A tela que agrega por operação chega numa versão futura do backend (RFC-0026). Até lá, o campo é enviado e ignorado sem erro.
+
 ## Garantias
 
 - **Fire-and-forget**: se o CloudBroker estiver fora, sua aplicação não é afetada

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudbroker-sdk",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "CloudBroker SDK — Token Intelligence & Operational Financial Intelligence",
   "repository": {
     "type": "git",
@@ -12,7 +12,7 @@
     ".": "./src/index.js"
   },
   "scripts": {
-    "test": "node src/test.js && node src/test-executions.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-operations.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.8.1",
+        sdkVersion: "0.9.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.8.1",
+        sdkVersion: "0.9.0",
         sentAt: new Date().toISOString(),
       };
 

package/src/cloud-wrapper.js

@@ -35,7 +35,7 @@ import {
   AZURE_COSMOS_ITEMS_OPS,
   AZURE_COSMOS_ITEMS_ITERATOR_OPS,
 } from "./pricing-cloud.js";
-import { cbStore } from "./context.js";
+import { cbStore, childOperationIds, operationFields } from "./context.js";
 import { resolveVersion } from "./executions.js";
 
 // Nomes de construtor do @azure/* → tipo do nó na cadeia de sub-clients.
@@ -177,6 +177,7 @@ export class CloudBrokerCloud {
       const cbLabel   = sendOptions?.cbLabel   || ctx.label   || null;
       const evProduct = sendOptions?.cbProduct || ctx.product || product || null;
       const evTeam    = sendOptions?.cbTeam    || ctx.team    || team    || null;
+      const op = operationFields();
       const bytesIn = CloudBrokerCloud.#inputBytes(command?.input);
 
       // Passa adiante apenas as options nativas — nunca vaza campos cb* pro AWS SDK.
@@ -204,6 +205,7 @@ export class CloudBrokerCloud {
           latencyMs: Date.now() - start,
           region:    clientRegion,
           version,
+          ...op,
         });
       } catch (err) {
         if (debug) console.warn("[CloudBroker] trackCloud error:", err.message);
@@ -243,7 +245,9 @@ export class CloudBrokerCloud {
 
     return (req, res, next) => {
       const safe = (fn) => { try { return fn(req); } catch { return undefined; } };
-      const ctx = { label: safe(resolveLabel), product: safe(resolveProduct), team: safe(resolveTeam) };
+      // Uma operação por requisição (RFC-0026): os eventos de nuvem e IA feitos
+      // durante a requisição levam o mesmo operationId.
+      const ctx = { label: safe(resolveLabel), product: safe(resolveProduct), team: safe(resolveTeam), ...childOperationIds() };
       try {
         if (executions && typeof executions.count === "function") executions.count(ctx);
       } catch { /* contador nunca derruba a requisição */ }
@@ -264,7 +268,8 @@ export class CloudBrokerCloud {
    * @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 };
+    // Uma operação por execução (RFC-0026); dentro de outra operação, vira filha.
+    const ctx = { label, product: options.product, team: options.team, ...childOperationIds() };
     try {
       if (options.executions && typeof options.executions.count === "function") options.executions.count(ctx);
     } catch { /* contador nunca derruba a execução */ }
@@ -383,6 +388,7 @@ export class CloudBrokerCloud {
         latencyMs,
         region:    env.region,
         version:   env.version,
+        ...operationFields(),
       });
     } catch (err) {
       if (env.debug) console.warn("[CloudBroker] trackCloud error:", err.message);

package/src/context.js

@@ -3,8 +3,14 @@
  * Permite atribuir um label de negócio (módulo / rota) a todas as chamadas de
  * nuvem disparadas dentro de uma requisição, sem precisar passar cbLabel manual
  * em cada `.send()`. Server-side apenas (Node).
+ *
+ * Desde a 0.9.0 (RFC-0026, custo por operação) o mesmo contexto carrega o
+ * `operationId` da execução corrente — não existe um segundo mecanismo de
+ * contexto. Os wrappers anexam esse id aos eventos, e o custo de UMA execução
+ * passa a ser um agrupamento na leitura (nenhuma escrita a mais).
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
 
 export const cbStore = new AsyncLocalStorage();
 
@@ -12,3 +18,53 @@ export const cbStore = new AsyncLocalStorage();
 export function currentLabel() {
   return cbStore.getStore()?.label || null;
 }
+
+/** Formato aceito para operationId: "op_" + UUID v7 em minúsculas. */
+export const OPERATION_ID_RE = /^op_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+/**
+ * Gera um operationId local ("op_" + UUID v7), sem ida ao backend.
+ * UUID v7 começa pelo timestamp em ms, então ids ordenam por tempo — útil para
+ * a leitura por janela no armazenamento analítico. Nunca contém dado do cliente.
+ */
+export function newOperationId(now = Date.now()) {
+  const b = randomBytes(16);
+  const ms = BigInt(Math.max(0, Math.floor(now)));
+  for (let i = 0; i < 6; i++) b[i] = Number((ms >> BigInt(8 * (5 - i))) & 0xffn);
+  b[6] = (b[6] & 0x0f) | 0x70; // versão 7
+  b[8] = (b[8] & 0x3f) | 0x80; // variante RFC 4122
+  const h = b.toString("hex");
+  return `op_${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+
+/**
+ * Ids de uma operação nova aberta DENTRO do contexto atual: o pai é a
+ * operação corrente, se houver. Nunca lança — sem id, a execução segue sem
+ * correlação, igual a antes da 0.9.0.
+ */
+export function childOperationIds() {
+  try {
+    const parent = cbStore.getStore()?.operationId;
+    return { operationId: newOperationId(), ...(parent ? { parentOperationId: parent } : {}) };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Campos de operação para anexar a um evento. Vazio fora de uma operação, para
+ * que o evento saia idêntico ao formato anterior (compatibilidade V1).
+ * Chamar no INÍCIO da chamada instrumentada (como o label), não na emissão:
+ * o fim de um stream pode rodar fora da operação que o abriu.
+ */
+export function operationFields() {
+  try {
+    const s = cbStore.getStore();
+    if (!s?.operationId) return {};
+    return s.parentOperationId
+      ? { operationId: s.operationId, parentOperationId: s.parentOperationId }
+      : { operationId: s.operationId };
+  } catch {
+    return {};
+  }
+}

package/src/index.js

@@ -7,6 +7,7 @@
  *   const openai = CloudBrokerAI.wrap(new OpenAI(), { apiKey: "cb-key-xxx", product: "checkout", team: "mobile" });
  */
 
+export { CloudBroker } from "./operation.js";
 export { CloudBrokerAI } from "./wrapper.js";
 export { CloudBrokerCloud } from "./cloud-wrapper.js";
 export { CloudBrokerClient } from "./client.js";

package/src/operation.js

@@ -0,0 +1,83 @@
+/**
+ * CloudBroker.operation — custo por operação (0.9.0, RFC-0026).
+ *
+ * Abre uma operação lógica (job, fila, operação de negócio) no MESMO contexto
+ * AsyncLocalStorage do expressMiddleware/trackExecution: as chamadas de
+ * nuvem e IA feitas dentro do callback levam o mesmo `operationId`. Não há
+ * evento de início/fim de operação — o custo da operação é a soma, na leitura,
+ * dos eventos que já são enviados (nenhuma escrita a mais por execução).
+ *
+ * Uso:
+ *   import { CloudBroker } from "cloudbroker-sdk";
+ *   await CloudBroker.operation("process-order", { product: "commerce", team: "checkout" }, async () => {
+ *     await s3.send(...);                       // wrapAWS herda o operationId
+ *     await openai.chat.completions.create(...); // CloudBrokerAI.wrap também
+ *   });
+ *
+ * Aninhada: a operação interna ganha id próprio e `parentOperationId` = o da
+ * externa; cada evento pertence só à operação mais interna (soma plana sem
+ * contagem dupla).
+ *
+ * De propósito FORA desta versão: tenantId (o tenant é sempre o da API key, no
+ * servidor), customerId e metadata (risco de dado pessoal — RFC-0026 §3).
+ */
+import { cbStore, childOperationIds, operationFields } from "./context.js";
+
+const OPERATION_TYPES = new Set(["http", "business", "job", "queue", "graphql", "database", "ai", "custom"]);
+
+/** Texto curto e sem caractere de controle; qualquer outra coisa vira null. */
+function text(v, max = 128) {
+  if (typeof v !== "string") return null;
+  const t = v.replace(/[\u0000-\u001F\u007F]/g, "").trim();
+  return t ? t.slice(0, max) : null;
+}
+
+export class CloudBroker {
+  /**
+   * @template T
+   * @param {string} name — nome da operação, de BAIXA cardinalidade
+   *   ("process-order", "GET /users/:id"), nunca com id ou dado do usuário.
+   *   Vira o label (trecho) das chamadas feitas dentro dela.
+   * @param {{label?: string, product?: string, team?: string, operationType?: string,
+   *   executions?: import("./executions.js").ExecutionCounter}} [options]
+   *   product/team ausentes herdam da operação externa.
+   * @param {() => T} callback — síncrono ou assíncrono
+   * @returns {T} o que o callback devolver (inclusive a Promise); o erro do
+   *   callback propaga intacto. A instrumentação em si nunca lança.
+   */
+  static operation(name, options, callback) {
+    if (typeof options === "function" && callback === undefined) { callback = options; options = {}; }
+    if (typeof callback !== "function") {
+      throw new TypeError("[CloudBroker] operation(name, options, callback): callback deve ser uma função.");
+    }
+
+    let ctx = null;
+    try {
+      const parent = cbStore.getStore() || {};
+      const o = options && typeof options === "object" ? options : {};
+      const opName = text(name);
+      ctx = {
+        label:         text(o.label) || opName || parent.label || null,
+        product:       text(o.product) ?? parent.product ?? null,
+        team:          text(o.team) ?? parent.team ?? null,
+        operationName: opName,
+        operationType: OPERATION_TYPES.has(o.operationType) ? o.operationType : "business",
+        ...childOperationIds(),
+      };
+      try {
+        if (o.executions && typeof o.executions.count === "function") o.executions.count(ctx);
+      } catch { /* contador nunca derruba a operação */ }
+    } catch {
+      ctx = null;
+    }
+    return ctx ? cbStore.run(ctx, callback) : callback();
+  }
+
+  /**
+   * Ids da operação corrente ({operationId, parentOperationId?}) ou `{}` fora
+   * de uma operação — ex.: para correlacionar com o log da própria aplicação.
+   */
+  static currentOperation() {
+    return operationFields();
+  }
+}

package/src/test-operations.js

@@ -0,0 +1,175 @@
+/**
+ * Custo por operação (0.9.0, RFC-0026). Execute: node src/test-operations.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 { CloudBroker, CloudBrokerCloud, CloudBrokerAI } from "./index.js";
+import { cbStore, newOperationId, OPERATION_ID_RE, operationFields } from "./context.js";
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log("✅", msg); };
+const tick = () => new Promise((r) => setTimeout(r, 20));
+
+const cloudSent = [];
+const aiSent = [];
+globalThis.fetch = async (url, opts) => {
+  const body = JSON.parse(opts.body);
+  if (String(url).includes("/api/cloud/events")) cloudSent.push(...body.events);
+  if (String(url).includes("/api/ai/events")) aiSent.push(...body.events);
+  return { ok: true, status: 200, json: async () => ({}) };
+};
+
+class S3Client {
+  constructor(cfg) { this.config = cfg; }
+  async send() { return { ContentLength: 10, $metadata: {} }; }
+}
+class PutObjectCommand { constructor(input) { this.input = input; } }
+class OpenAI {
+  constructor() {
+    this.chat = { completions: { create: async (p) => ({ model: p.model, usage: { prompt_tokens: 100, completion_tokens: 50 } }) } };
+  }
+}
+
+const s3 = CloudBrokerCloud.wrapAWS(new S3Client({ region: "us-east-2" }), { apiKey: "cb-test", product: "loja" });
+const openai = CloudBrokerAI.wrap(new OpenAI(), { apiKey: "cb-test", product: "loja" });
+const put = () => s3.send(new PutObjectCommand({ Bucket: "b", Key: "k", Body: "x" }));
+const ask = () => openai.chat.completions.create({ model: "gpt-4o-mini", messages: [] });
+
+// ─── id ──────────────────────────────────────────────────────────────────────
+{
+  const a = newOperationId(Date.parse("2026-10-17T12:00:00Z"));
+  const b = newOperationId(Date.parse("2026-10-17T12:00:01Z"));
+  ok(OPERATION_ID_RE.test(a) && OPERATION_ID_RE.test(b), "operationId = op_ + UUID v7 (versão 7, variante RFC 4122)");
+  ok(a < b, "ids ordenam por tempo (UUID v7 começa pelo timestamp)");
+  const many = new Set(Array.from({ length: 2000 }, () => newOperationId()));
+  ok(many.size === 2000, "2000 ids no mesmo ms não colidem");
+}
+
+// ─── critério de saída da Fase 1: S3 + IA no mesmo operationId ───────────────
+{
+  cloudSent.length = 0; aiSent.length = 0;
+  let inside;
+  const r = await CloudBroker.operation("process-order", { team: "checkout" }, async () => {
+    inside = CloudBroker.currentOperation().operationId;
+    await put();
+    await ask();
+    return 42;
+  });
+  await tick();
+  ok(r === 42, "devolve o que o callback devolver");
+  ok(OPERATION_ID_RE.test(inside), "currentOperation() expõe o id dentro da operação");
+  ok(cloudSent.length === 1 && aiSent.length === 1, "1 evento de nuvem + 1 de IA (nenhum evento de ciclo de vida)");
+  ok(cloudSent[0].operationId === inside && aiSent[0].operationId === inside, "S3 e IA saem com o MESMO operationId");
+  ok(cloudSent[0].label === "process-order" && aiSent[0].label === "process-order", "nome da operação vira o label (trecho)");
+  ok(cloudSent[0].team === "checkout" && cloudSent[0].product === "loja", "team da operação; product estático do wrapAWS preservado");
+  ok(!("parentOperationId" in cloudSent[0]), "operação raiz não tem pai");
+}
+
+// ─── fora de operação: evento idêntico ao V1 ─────────────────────────────────
+{
+  cloudSent.length = 0; aiSent.length = 0;
+  await put(); await ask(); await tick();
+  ok(!("operationId" in cloudSent[0]) && !("operationId" in aiSent[0]), "sem operação ativa o evento não ganha campo novo (V1)");
+  ok(Object.keys(operationFields()).length === 0 && Object.keys(CloudBroker.currentOperation()).length === 0, "fora de operação: {}");
+}
+
+// ─── aninhada: id próprio, pai, sem contagem dupla ───────────────────────────
+{
+  cloudSent.length = 0;
+  let outerId, innerId;
+  await CloudBroker.operation("checkout", { product: "commerce" }, async () => {
+    outerId = CloudBroker.currentOperation().operationId;
+    await put();
+    await CloudBroker.operation("calculate-shipping", {}, async () => {
+      innerId = CloudBroker.currentOperation().operationId;
+      await put();
+      await put();
+    });
+    ok(CloudBroker.currentOperation().operationId === outerId, "ao sair da filha, volta à operação externa");
+  });
+  await tick();
+  const outer = cloudSent.filter((e) => e.operationId === outerId);
+  const inner = cloudSent.filter((e) => e.operationId === innerId);
+  ok(innerId !== outerId, "filha recebe operationId próprio");
+  ok(outer.length === 1 && inner.length === 2, "cada evento pertence só à operação mais interna (soma plana sem contagem dupla)");
+  ok(inner.every((e) => e.parentOperationId === outerId), "eventos da filha levam parentOperationId = externa");
+  ok(inner[0].product === "commerce" && inner[0].label === "calculate-shipping", "filha herda product da externa; label é o próprio nome");
+}
+
+// ─── middleware e trackExecution criam operação ──────────────────────────────
+{
+  const mw = CloudBrokerCloud.expressMiddleware({ label: "POST /orders" });
+  const ids = [];
+  for (let i = 0; i < 2; i++) {
+    await new Promise((r) => mw({ method: "POST", path: "/orders" }, {}, () => { ids.push(cbStore.getStore().operationId); r(); }));
+  }
+  ok(ids.every((id) => OPERATION_ID_RE.test(id)) && ids[0] !== ids[1], "expressMiddleware: uma operação nova por requisição");
+
+  let jobId, jobParent;
+  await CloudBroker.operation("batch", {}, async () => {
+    const outer = CloudBroker.currentOperation().operationId;
+    await CloudBrokerCloud.trackExecution("job:item", async () => {
+      jobId = cbStore.getStore().operationId; jobParent = cbStore.getStore().parentOperationId;
+    });
+    ok(jobParent === outer && jobId !== outer, "trackExecution dentro de operação vira filha");
+  });
+  ok(OPERATION_ID_RE.test(jobId), "trackExecution gera operationId");
+}
+
+// ─── síncrono, erro, uso indevido ────────────────────────────────────────────
+{
+  ok(CloudBroker.operation("sync", {}, () => 7) === 7, "callback síncrono devolve valor direto (sem Promise)");
+  ok(CloudBroker.operation("sem-options", () => "ok") === "ok", "options é opcional");
+  class MeuErro extends Error {}
+  let e1; try { CloudBroker.operation("x", {}, () => { throw new MeuErro("sync"); }); } catch (e) { e1 = e; }
+  ok(e1 instanceof MeuErro && e1.message === "sync", "erro síncrono do callback propaga com o mesmo tipo");
+  let e2; try { await CloudBroker.operation("x", {}, async () => { throw new MeuErro("async"); }); } catch (e) { e2 = e; }
+  ok(e2 instanceof MeuErro && e2.message === "async", "rejeição do callback propaga com o mesmo tipo");
+  let e3; try { CloudBroker.operation("x", {}); } catch (e) { e3 = e; }
+  ok(e3 instanceof TypeError, "sem callback: TypeError claro (erro de uso, não de instrumentação)");
+  ok(CloudBroker.operation({ evil: 1 }, null, () => "segue") === "segue", "nome/options inválidos não derrubam a execução");
+  const contadorQuebrado = { count() { throw new Error("x"); } };
+  ok(CloudBroker.operation("x", { executions: contadorQuebrado }, () => 1) === 1, "contador que lança não derruba a operação");
+}
+
+// ─── fronteira de privacidade (RFC-0026 §3) ──────────────────────────────────
+{
+  cloudSent.length = 0;
+  await CloudBroker.operation("x\n\u0007forjado", { tenantId: "outro-tenant", customerId: "a@b.com", metadata: { cpf: "1" } }, async () => { await put(); });
+  await tick();
+  const ev = cloudSent[0];
+  ok(!("tenantId" in ev) && !("customerId" in ev) && !("metadata" in ev), "tenantId/customerId/metadata NÃO saem do SDK nesta fase");
+  ok(ev.label === "xforjado", "nome da operação sem caractere de controle (não forja linha de log)");
+}
+
+// ─── Azure e Anthropic também propagam ───────────────────────────────────────
+{
+  class BlockBlobClient { async uploadData() { return { etag: "1" }; } }
+  class ContainerClient { getBlockBlobClient() { return new BlockBlobClient(); } }
+  class BlobServiceClient { getContainerClient() { return new ContainerClient(); } }
+  class Anthropic {
+    constructor() { this.messages = { create: async (p) => ({ model: p.model, usage: { input_tokens: 10, output_tokens: 5 } }) }; }
+  }
+  const blob = CloudBrokerCloud.wrapAzure(new BlobServiceClient(), { apiKey: "cb-test" });
+  const claude = CloudBrokerAI.wrap(new Anthropic(), { apiKey: "cb-test" });
+  cloudSent.length = 0; aiSent.length = 0;
+  let id;
+  await CloudBroker.operation("azure-op", {}, async () => {
+    id = CloudBroker.currentOperation().operationId;
+    await blob.getContainerClient("c").getBlockBlobClient("b").uploadData(Buffer.from("x"));
+    await claude.messages.create({ model: "claude-haiku-4-5", max_tokens: 10, messages: [] });
+  });
+  await tick();
+  ok(cloudSent[0]?.provider === "azure" && cloudSent[0].operationId === id, "wrapAzure propaga o operationId");
+  ok(aiSent[0]?.provider === "anthropic" && aiSent[0].operationId === id, "wrap Anthropic propaga o operationId");
+}
+
+// ─── versão anunciada = package.json ─────────────────────────────────────────
+{
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  const client = readFileSync(new URL("./client.js", import.meta.url), "utf8");
+  ok(pkg.version === "0.9.0" && [...client.matchAll(/sdkVersion:\s*"([^"]+)"/g)].every((m) => m[1] === pkg.version), "sdkVersion 0.9.0 nos eventos");
+}
+
+console.log(`\n${pass} asserções ok — custo por operação`);

package/src/wrapper.js

@@ -5,7 +5,7 @@
 
 import { CloudBrokerClient } from "./client.js";
 import { PRICING, priceGemini, priceAnthropic } from "./pricing.js";
-import { cbStore } from "./context.js";
+import { cbStore, operationFields } from "./context.js";
 
 /**
  * Evento de uma chamada da Anthropic. O preço vem de `priceAnthropic`: inclui
@@ -122,6 +122,7 @@ export class CloudBrokerAI {
       // Mesma precedência de cloud-wrapper.js: explícito na chamada > contexto
       // cbStore (expressMiddleware) > nenhum. Nunca vaza cbLabel pro SDK do provider.
       const cbLabel = options?.cbLabel || cbStore.getStore()?.label || null;
+      const op = operationFields(); // capturado no início, como o label (RFC-0026)
       const { cbLabel: _l, ...providerOptions } = options || {};
       const fwdOptions = Object.keys(providerOptions).length ? providerOptions : undefined;
 
@@ -159,6 +160,7 @@ export class CloudBrokerAI {
               latencyMs:   Date.now() - start,
               endpoint:    "chat.completions",
               streaming:   true,
+              ...op,
             });
           } catch (err) {
             if (debug) console.warn("[CloudBroker] track error:", err.message);
@@ -192,6 +194,7 @@ export class CloudBrokerAI {
           costUSD:       parseFloat(costUSD.toFixed(6)),
           latencyMs:     ms,
           endpoint:      "chat.completions",
+          ...op,
         });
       } catch (err) {
         if (debug) console.warn("[CloudBroker] track error:", err.message);
@@ -209,6 +212,7 @@ export class CloudBrokerAI {
     client.messages.create = async (params, options) => {
       const start = Date.now();
       const cbLabel = options?.cbLabel || cbStore.getStore()?.label || null;
+      const op = operationFields(); // capturado no início, como o label (RFC-0026)
       const { cbLabel: _l, ...providerOptions } = options || {};
       const fwdOptions = Object.keys(providerOptions).length ? providerOptions : undefined;
 
@@ -230,7 +234,7 @@ export class CloudBrokerAI {
         };
         const onDone = () => {
           try {
-            cb.track(anthropicEvent(model, usage, { product, team, label: cbLabel, start, streaming: true }));
+            cb.track({ ...anthropicEvent(model, usage, { product, team, label: cbLabel, start, streaming: true }), ...op });
           } catch (err) {
             if (debug) console.warn("[CloudBroker] track error:", err.message);
           }
@@ -245,7 +249,7 @@ export class CloudBrokerAI {
 
       try {
         const model = res.model || params.model || "unknown";
-        cb.track(anthropicEvent(model, res.usage, { product, team, label: cbLabel, start, latencyMs: ms }));
+        cb.track({ ...anthropicEvent(model, res.usage, { product, team, label: cbLabel, start, latencyMs: ms }), ...op });
       } catch (err) {
         if (debug) console.warn("[CloudBroker] track error:", err.message);
       }
@@ -324,14 +328,15 @@ export class CloudBrokerAI {
     models.generateContent = async (params, options) => {
       const start = Date.now();
       const { label, fwd } = splitLabel(params, options);
+      const op = operationFields();
 
       const res = await originalGenerate(fwd);
 
       try {
         const model = res?.modelVersion || params?.model || "unknown";
-        cb.track(buildEvent(model, res?.usageMetadata, {
+        cb.track({ ...buildEvent(model, res?.usageMetadata, {
           label, start, streaming: false, endpoint: "models.generateContent",
-        }));
+        }), ...op });
       } catch (err) {
         if (debug) console.warn("[CloudBroker] track error:", err.message);
       }
@@ -345,6 +350,7 @@ export class CloudBrokerAI {
       models.generateContentStream = async (params, options) => {
         const start = Date.now();
         const { label, fwd } = splitLabel(params, options);
+        const op = operationFields();
 
         const stream = await originalStream(fwd);
 
@@ -358,9 +364,9 @@ export class CloudBrokerAI {
         };
         const onDone = () => {
           try {
-            cb.track(buildEvent(model, usage, {
+            cb.track({ ...buildEvent(model, usage, {
               label, start, streaming: true, endpoint: "models.generateContentStream",
-            }));
+            }), ...op });
           } catch (err) {
             if (debug) console.warn("[CloudBroker] track error:", err.message);
           }