cloudbroker-sdk 0.8.1 → 0.9.1

package/README.md

@@ -349,6 +349,46 @@ await CloudBrokerCloud.trackExecution("job:fechamento-mensal", () => fecharMes()
   de um deploy pela versão que de fato rodou.
 - No shutdown: `await execucoes.flush(); execucoes.stop();`.
 
+#### Falhas e duração (0.9.1)
+
+Sem mudar nada no seu código, `expressMiddleware`, `trackExecution` e
+`CloudBroker.operation` passam a informar, junto com a contagem, quantas
+execuções **terminaram**, quantas **falharam** e a **duração** somada:
+
+- requisição: termina quando a resposta é enviada; status 5xx = falha. Uma
+  requisição abortada antes de responder conta como execução, mas não como
+  terminada;
+- `trackExecution`/`operation`: falha = o callback lançou ou a Promise rejeitou.
+  O retorno e o erro chegam intactos ao seu código.
+
+Por isso a taxa de falha e a duração média são calculadas sobre as execuções
+**terminadas**, não sobre o total. Duração por execução tem teto de 24 h.
+
+Para contar à mão: `const fim = execucoes.count({ label }); … fim({ failed })`.
+
+### 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.1",
   "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.1",
         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.1",
         sentAt: new Date().toISOString(),
       };
 

package/src/cloud-wrapper.js

@@ -35,7 +35,8 @@ import {
   AZURE_COSMOS_ITEMS_OPS,
   AZURE_COSMOS_ITEMS_ITERATOR_OPS,
 } from "./pricing-cloud.js";
-import { cbStore } from "./context.js";
+import { runObserved } from "./observe.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 +178,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 +206,7 @@ export class CloudBrokerCloud {
           latencyMs: Date.now() - start,
           region:    clientRegion,
           version,
+          ...op,
         });
       } catch (err) {
         if (debug) console.warn("[CloudBroker] trackCloud error:", err.message);
@@ -243,9 +246,18 @@ 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);
+        if (executions && typeof executions.count === "function") {
+          const fim = executions.count(ctx);
+          // Fim da requisição: resposta enviada. 5xx = falha. Abortada antes
+          // de responder não chega aqui — conta só em executions, não em completed.
+          if (typeof fim === "function" && typeof res?.once === "function") {
+            res.once("finish", () => { try { fim({ failed: res.statusCode >= 500 }); } catch { /* nunca lança */ } });
+          }
+        }
       } catch { /* contador nunca derruba a requisição */ }
       cbStore.run(ctx, () => next());
     };
@@ -264,11 +276,13 @@ 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() };
+    let fim = null;
     try {
-      if (options.executions && typeof options.executions.count === "function") options.executions.count(ctx);
+      if (options.executions && typeof options.executions.count === "function") fim = options.executions.count(ctx);
     } catch { /* contador nunca derruba a execução */ }
-    return cbStore.run(ctx, fn);
+    return runObserved(ctx, fn, fim);
   }
 
   /**
@@ -383,6 +397,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/executions.js

@@ -20,6 +20,14 @@
  *   • contagem com mais de 7 dias sem conseguir enviar é descartada (o backend
  *     recusa, e reenviar para sempre seria inútil).
  *
+ * Falhas e duração (0.9.1, RFC-0026): `count()` devolve uma função de
+ * término. Chamada no fim (`fim({ failed })`), ela soma na MESMA combinação
+ * da hora de início: `completed`, `failures` e `durationMsSum` (relógio
+ * monotônico). Execução que nunca termina (requisição abortada, processo
+ * morto) conta em `count` e não em `completed` — por isso a taxa de falha e a
+ * duração média se calculam sobre `completed`. O expressMiddleware e o
+ * trackExecution chamam o término sozinhos.
+ *
  * Uso:
  *   const execucoes = new ExecutionCounter({ apiKey: "cb-key-xxx" }); // version ← CLOUDBROKER_VERSION
  *   app.use(CloudBrokerCloud.expressMiddleware({ label: ..., executions: execucoes }));
@@ -29,6 +37,8 @@
 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;
+const MAX_DURATION_MS = 24 * HOUR_MS;   // o backend recusa acima disso
+const NOOP = () => {};
 
 /** Versão do código do cliente: explícita > CLOUDBROKER_VERSION > null. */
 export function resolveVersion(explicit) {
@@ -48,10 +58,13 @@ export class ExecutionCounter {
   #debug;
   #maxKeys;
   #now;
+  #mono;
   #pending = new Map();
   #flushing = false;
   #timer = null;
   dropped = 0;
+  /** Términos que não couberam no teto de combinações (sem a execução perdida). */
+  droppedCompletions = 0;
 
   /**
    * @param {object} options
@@ -62,7 +75,7 @@ export class ExecutionCounter {
    * @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 } = {}) {
+  constructor({ apiKey, version, endpoint = DEFAULT_EXECUTIONS_ENDPOINT, flushIntervalMs = 60_000, maxKeys = 200, debug = false, now, monotonicNow } = {}) {
     if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
     this.#apiKey = apiKey;
     this.#endpoint = endpoint;
@@ -70,6 +83,7 @@ export class ExecutionCounter {
     this.#debug = debug;
     this.#maxKeys = Math.max(1, Math.min(200, Math.floor(maxKeys) || 200));
     this.#now = typeof now === "function" ? now : Date.now;
+    this.#mono = typeof monotonicNow === "function" ? monotonicNow : () => performance.now();
     if (flushIntervalMs > 0) {
       this.#timer = setInterval(() => { this.flush(); }, flushIntervalMs);
       if (typeof this.#timer?.unref === "function") this.#timer.unref();
@@ -85,21 +99,48 @@ export class ExecutionCounter {
   /**
    * Soma uma execução do trecho. Nunca lança.
    * @param {{label?: string, product?: string}} ctx
+   * @returns {(result?: {failed?: boolean}) => void} término da execução —
+   *   soma completed/failures/durationMsSum; só a 1ª chamada conta. Sem rótulo
+   *   (execução não contada), é uma função vazia.
    */
   count(ctx) {
     try {
       const label = ctx?.label, product = ctx?.product;
-      if (typeof label !== "string" || !label.trim()) return;
+      if (typeof label !== "string" || !label.trim()) return NOOP;
       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 });
+      if (cur) cur.count++;
+      else if (this.#pending.size >= this.#maxKeys) { this.dropped++; return NOOP; }
+      else this.#pending.set(key, { label, product: prod, version: this.#version, hour, count: 1 });
+      const start = this.#mono();
+      let done = false;
+      return (result) => {
+        if (done) return;
+        done = true;
+        try { this.#complete(key, { label, product: prod, hour }, start, result?.failed === true); }
+        catch (err) { if (this.#debug) console.warn("[CloudBroker] executions finish error:", err.message); }
+      };
     } catch (err) {
       if (this.#debug) console.warn("[CloudBroker] executions.count error:", err.message);
+      return NOOP;
+    }
+  }
+
+  #complete(key, base, start, failed) {
+    const d = this.#mono() - start;
+    const ms = Number.isFinite(d) && d > 0 ? Math.min(Math.round(d), MAX_DURATION_MS) : 0;
+    let it = this.#pending.get(key);
+    if (!it) {
+      // A combinação já foi enviada: o término vai num item só com fim (count 0).
+      if (this.#pending.size >= this.#maxKeys) { this.droppedCompletions++; return; }
+      it = { ...base, version: this.#version, count: 0 };
+      this.#pending.set(key, it);
     }
+    it.completed = (it.completed || 0) + 1;
+    it.failures = (it.failures || 0) + (failed ? 1 : 0);
+    it.durationMsSum = (it.durationMsSum || 0) + ms;
   }
 
   /** Envia o pendente. Nunca lança; em falha transitória, a contagem volta para a fila. */
@@ -138,8 +179,14 @@ export class ExecutionCounter {
       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);
+      if (cur) {
+        cur.count += it.count;
+        if (it.completed) {
+          cur.completed = (cur.completed || 0) + it.completed;
+          cur.failures = (cur.failures || 0) + it.failures;
+          cur.durationMsSum = (cur.durationMsSum || 0) + it.durationMsSum;
+        }
+      } else if (this.#pending.size < this.#maxKeys) this.#pending.set(key, it);
       else this.dropped += it.count;
     }
   }

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/observe.js

@@ -0,0 +1,29 @@
+/**
+ * Roda `fn` no contexto `ctx` e avisa o término da execução (0.9.1, RFC-0026).
+ *
+ * `fim` é a função devolvida por ExecutionCounter.count(); null = sem contador.
+ * Garantias: o retorno de `fn` (inclusive a MESMA Promise) e o erro de `fn`
+ * chegam intactos ao chamador; a observação nunca lança nem cria rejeição
+ * não tratada nova (o ramo `.then` trata as duas saídas).
+ */
+import { cbStore } from "./context.js";
+
+export function runObserved(ctx, fn, fim) {
+  if (typeof fim !== "function") return cbStore.run(ctx, fn);
+  const end = (failed) => { try { fim({ failed }); } catch { /* nunca lança */ } };
+  let result;
+  try {
+    result = cbStore.run(ctx, fn);
+  } catch (err) {
+    end(true);
+    throw err;
+  }
+  let then = null;
+  try { then = result !== null && (typeof result === "object" || typeof result === "function") ? result.then : null; } catch { then = null; }
+  if (typeof then === "function") {
+    try { then.call(result, () => end(false), () => end(true)); } catch { end(false); }
+  } else {
+    end(false);
+  }
+  return result;
+}

package/src/operation.js

@@ -0,0 +1,84 @@
+/**
+ * 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";
+import { runObserved } from "./observe.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, fim = 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") fim = o.executions.count(ctx);
+      } catch { /* contador nunca derruba a operação */ }
+    } catch {
+      ctx = null;
+    }
+    return ctx ? runObserved(ctx, callback, fim) : 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-executions.js

@@ -178,6 +178,99 @@ ok(resolveVersion("x".repeat(100)).length === 64, "versão com teto de 64");
   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");
 }
 
+// ─── falhas e duração (0.9.1, RFC-0026) ──────────────────────────────────────
+{
+  const { EventEmitter } = await import("node:events");
+  let mono = 1000;
+  const c = mk({ monotonicNow: () => mono });
+  const fim1 = c.count({ label: "checkout", product: "Loja" });
+  const fim2 = c.count({ label: "checkout", product: "Loja" });
+  c.count({ label: "checkout", product: "Loja" });            // em andamento: sem fim
+  mono += 120; fim1();
+  mono += 30; fim2({ failed: true });
+  fim1({ failed: true });                                      // 2ª chamada não conta
+  ok(typeof c.count({}) === "function", "count sem rótulo devolve término vazio (chamável)");
+  await c.flush();
+  let it = sent.at(-1).body.executions[0];
+  ok(it.count === 3 && it.completed === 2 && it.failures === 1 && it.durationMsSum === 270, `contagem 3, fim 2, 1 falha, duração somada (veio ${JSON.stringify(it)})`);
+
+  const fim3 = c.count({ label: "checkout", product: "Loja" });
+  await c.flush();                                             // início já enviado
+  mono += 50; fim3();
+  await c.flush();
+  it = sent.at(-1).body.executions[0];
+  ok(it.count === 0 && it.completed === 1 && it.durationMsSum === 50 && it.hour === "2026-10-12T15:00:00.000Z", "término depois do envio do início → item só com fim, na hora do INÍCIO");
+
+  const c0 = mk({ monotonicNow: () => mono });
+  c0.count({ label: "v1" });
+  await c0.flush();
+  ok(!("completed" in sent.at(-1).body.executions[0]), "sem término observado não manda completed (ausente ≠ 0)");
+
+  const cNeg = mk({ monotonicNow: () => NaN });
+  cNeg.count({ label: "n" })();
+  await cNeg.flush();
+  ok(sent.at(-1).body.executions[0].durationMsSum === 0, "relógio inválido → duração 0, nunca NaN");
+  let longa = 0; const cL = mk({ monotonicNow: () => longa });
+  const fimL = cL.count({ label: "longa" }); longa = 48 * 3_600_000; fimL();
+  await cL.flush();
+  ok(sent.at(-1).body.executions[0].durationMsSum === 24 * 3_600_000, "duração limitada a 24 h (teto do backend)");
+
+  const cR = mk({ monotonicNow: () => mono });
+  respond = () => ({ ok: false, status: 503 });
+  cR.count({ label: "r" })({ failed: true });
+  await cR.flush();
+  respond = () => ({ ok: true, status: 200 });
+  cR.count({ label: "r" })();
+  await cR.flush();
+  it = sent.at(-1).body.executions[0];
+  ok(it.count === 2 && it.completed === 2 && it.failures === 1, "falha transitória: fim volta à fila e soma com o seguinte");
+
+  // middleware: 'finish' com 5xx = falha; abortada (sem finish) não completa
+  const cm = mk({ monotonicNow: () => mono });
+  const mw = CloudBrokerCloud.expressMiddleware({ label: "mod", executions: cm });
+  const r1 = Object.assign(new EventEmitter(), { statusCode: 200 });
+  const r2 = Object.assign(new EventEmitter(), { statusCode: 503 });
+  const r3 = Object.assign(new EventEmitter(), { statusCode: 200 });
+  for (const r of [r1, r2, r3]) await new Promise((ok_) => mw({ method: "GET", path: "/" }, r, ok_));
+  r1.emit("finish"); r2.emit("finish"); r3.emit("close");
+  await cm.flush();
+  it = sent.at(-1).body.executions[0];
+  ok(it.count === 3 && it.completed === 2 && it.failures === 1, "middleware: 2xx ok, 5xx falha, abortada só em count");
+
+  // trackExecution e operation: sync, async, erro; retorno e erro intactos
+  const ct = mk({ monotonicNow: () => mono });
+  const p = Promise.resolve(9);
+  ok(CloudBrokerCloud.trackExecution("t", () => p, { executions: ct }) === p, "trackExecution devolve a MESMA Promise");
+  ok(CloudBrokerCloud.trackExecution("t", () => 1, { executions: ct }) === 1, "síncrono devolve o valor");
+  class E extends Error {}
+  let e1; try { CloudBrokerCloud.trackExecution("t", () => { throw new E("s"); }, { executions: ct }); } catch (e) { e1 = e; }
+  let e2; try { await CloudBrokerCloud.trackExecution("t", async () => { throw new E("a"); }, { executions: ct }); } catch (e) { e2 = e; }
+  ok(e1 instanceof E && e2 instanceof E, "erro síncrono e assíncrono propagam com o mesmo tipo");
+  const { CloudBroker } = await import("./operation.js");
+  await CloudBroker.operation("t", { executions: ct }, async () => 1);
+  let e3; try { await CloudBroker.operation("t", { executions: ct }, async () => { throw new E("o"); }); } catch (e) { e3 = e; }
+  ok(e3 instanceof E, "CloudBroker.operation propaga o erro");
+  await new Promise((r) => setTimeout(r, 10));
+  await ct.flush();
+  it = sent.at(-1).body.executions[0];
+  ok(it.count === 6 && it.completed === 6 && it.failures === 3, `trackExecution + operation: 6 execuções, 3 falhas (veio ${it.count}/${it.completed}/${it.failures})`);
+
+  // nenhuma rejeição não tratada nova
+  const unhandled = [];
+  const h = (r) => unhandled.push(r);
+  process.on("unhandledRejection", h);
+  const pr = CloudBrokerCloud.trackExecution("t", async () => { throw new E("x"); }, { executions: ct });
+  await pr.catch(() => {});
+  await new Promise((r) => setTimeout(r, 20));
+  process.off("unhandledRejection", h);
+  ok(unhandled.length === 0, "a observação não cria rejeição não tratada");
+
+  const quebrado = { count() { return () => { throw new Error("x"); }; } };
+  ok(CloudBrokerCloud.trackExecution("t", () => 5, { executions: quebrado }) === 5, "término que lança não derruba a execução");
+  const thenHostil = { get then() { throw new Error("x"); } };
+  ok(CloudBrokerCloud.trackExecution("t", () => thenHostil, { executions: ct }) === thenHostil, "retorno com 'then' hostil volta intacto");
+}
+
 // ─── versão do pacote ────────────────────────────────────────────────────────
 {
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));

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.1" && [...client.matchAll(/sdkVersion:\s*"([^"]+)"/g)].every((m) => m[1] === pkg.version), "sdkVersion 0.9.1 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);
           }