cloudbroker-sdk 0.4.0 → 0.6.0

package/src/cloud-wrapper.js

@@ -1,9 +1,13 @@
 /**
- * CloudBrokerCloud — atribuição de custo de nuvem a nível de código (MVP).
+ * CloudBrokerCloud — atribuição de custo de nuvem a nível de código.
  *
- * Envolve um client do AWS SDK v3 (S3 / DynamoDB) e, a cada chamada `.send()`,
- * estima o custo de requests + transferência e envia um evento fire-and-forget
- * ao backend. Não altera o comportamento do client original.
+ * wrapAWS: envolve um client do AWS SDK v3 (S3 / DynamoDB) e, a cada chamada
+ * `.send()`, estima o custo de requests + transferência.
+ * wrapAzure: envolve um client do Azure SDK (Blob Storage / Cosmos DB) e
+ * intercepta os métodos de data-plane na cadeia de sub-clients — Cosmos usa o
+ * requestCharge (RUs) real de cada resposta.
+ * Ambos enviam eventos fire-and-forget ao backend, sem alterar o comportamento
+ * do client original.
  *
  * Uso:
  *   import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
@@ -23,9 +27,119 @@
  */
 
 import { CloudBrokerClient } from "./client.js";
-import { estimateCloudCost } from "./pricing-cloud.js";
+import {
+  estimateCloudCost,
+  AZURE_BLOB_OPS,
+  AZURE_BLOB_ITERATOR_OPS,
+  AZURE_COSMOS_NODE_OPS,
+  AZURE_COSMOS_ITEMS_OPS,
+  AZURE_COSMOS_ITEMS_ITERATOR_OPS,
+} from "./pricing-cloud.js";
 import { cbStore } from "./context.js";
 
+// Nomes de construtor do @azure/* → tipo do nó na cadeia de sub-clients.
+const AZURE_BLOB_KIND = {
+  BlobServiceClient: "service",
+  ContainerClient:   "container",
+  BlobClient:        "blob",
+  BlockBlobClient:   "blob",
+  AppendBlobClient:  "blob",
+  PageBlobClient:    "blob",
+};
+const AZURE_COSMOS_KIND = {
+  CosmosClient: "client",
+  Database:     "database",
+  Container:    "container",
+  Item:         "item",
+};
+const AZURE_BLOB_FACTORIES = [
+  "getContainerClient", "getBlobClient", "getBlockBlobClient",
+  "getAppendBlobClient", "getPageBlobClient",
+];
+
+/** Objeto literal — exclui Buffer/Uint8Array/Array/instâncias de classe do SDK. */
+function isPlainObject(v) {
+  if (v === null || typeof v !== "object") return false;
+  if (Buffer.isBuffer(v) || ArrayBuffer.isView(v) || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * RUs realmente cobradas pelo Cosmos. Respostas de `bulk`/`batch` não trazem
+ * requestCharge no topo — vêm por operação, e somar é o número certo (senão
+ * um bulk de 1000 escritas seria contabilizado como 1 leitura).
+ */
+function readRequestCharge(result) {
+  if (!result) return undefined;
+  if (typeof result.requestCharge === "number") return result.requestCharge;
+  const rows = Array.isArray(result) ? result
+             : Array.isArray(result?.result) ? result.result
+             : null;
+  if (rows) {
+    let sum = 0, saw = false;
+    for (const r of rows) {
+      if (typeof r?.requestCharge === "number") { sum += r.requestCharge; saw = true; }
+    }
+    if (saw) return sum;
+  }
+  const header = result.headers?.["x-ms-request-charge"];
+  if (header != null) {
+    const v = parseFloat(header);
+    if (Number.isFinite(v)) return v;
+  }
+  return undefined;
+}
+
+/**
+ * Instrumenta um async iterable para emitir só quando uma página é DE FATO
+ * buscada (o iterator do Azure é lazy — nenhum HTTP acontece na criação).
+ * `onceOnly` = emite 1 evento na primeira busca (for-await direto, onde o SDK
+ * pagina internamente e não dá pra observar as páginas seguintes).
+ */
+function wrapAsyncIterable(iterable, emit, onceOnly) {
+  let emitted = false;
+  const maybeEmit = (start) => {
+    if (onceOnly && emitted) return;
+    emitted = true;
+    emit(start);
+  };
+
+  // PagedAsyncIterableIterator: [Symbol.asyncIterator]() devolve `this`, então
+  // embrulhar `next` já cobre o for-await.
+  if (typeof iterable.next === "function") {
+    const orig = iterable.next.bind(iterable);
+    iterable.next = async (...a) => {
+      const start = Date.now();
+      const r = await orig(...a);
+      if (!r?.done) maybeEmit(start);
+      return r;
+    };
+    return iterable;
+  }
+
+  if (typeof iterable[Symbol.asyncIterator] === "function") {
+    const origAsync = iterable[Symbol.asyncIterator].bind(iterable);
+    iterable[Symbol.asyncIterator] = () => {
+      const it = origAsync();
+      const n  = it.next.bind(it);
+      const wrapped = {
+        next: async (...a) => {
+          const start = Date.now();
+          const r = await n(...a);
+          if (!r?.done) maybeEmit(start);
+          return r;
+        },
+        [Symbol.asyncIterator]() { return wrapped; },
+      };
+      if (typeof it.return === "function") wrapped.return = it.return.bind(it);
+      if (typeof it.throw  === "function") wrapped.throw  = it.throw.bind(it);
+      return wrapped;
+    };
+  }
+  return iterable;
+}
+
 export class CloudBrokerCloud {
   /**
    * @param {object} client  — instância do AWS SDK v3 (ex: new S3Client())
@@ -124,6 +238,418 @@ export class CloudBrokerCloud {
     };
   }
 
+  /**
+   * 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.
+   *
+   * Azure não tem um `.send()` único como o AWS SDK v3: cada sub-client tem
+   * métodos próprios, e as fábricas (getContainerClient → getBlockBlobClient,
+   * database → container → items) criam sub-clients novos a cada chamada.
+   * Por isso a interceptação aqui é em cadeia: métodos de fábrica retornam
+   * sub-clients já embrulhados, e só os métodos de data-plane conhecidos são
+   * rastreados — qualquer método desconhecido passa direto, intocado.
+   *
+   * Garantia (igual ao wrapAWS): nada além da própria chamada Azure pode
+   * lançar. Se a instrumentação falhar, a aplicação do cliente não percebe.
+   *
+   * Cosmos: usa o requestCharge (RUs) REAL que o servidor retorna em cada
+   * resposta. O PREÇO por RU assumido é o de **serverless** — em throughput
+   * provisionado a Azure cobra RU/s reservada por hora, modelo que o SDK não
+   * modela ainda (ver README).
+   *
+   * Uso:
+   *   const blobSvc = CloudBrokerCloud.wrapAzure(
+   *     BlobServiceClient.fromConnectionString(conn),
+   *     { apiKey: "cb-key-xxx", product: "checkout", team: "mobile" },
+   *   );
+   *   // label opcional dentro do objeto de options nativo do método:
+   *   await blobSvc.getContainerClient("docs").getBlockBlobClient("nf.pdf")
+   *     .uploadData(buf, { cbLabel: "upload-nota-fiscal" });
+   *
+   * @param {object} client — BlobServiceClient | ContainerClient | Blob*Client
+   *                          | CosmosClient | Database | Container
+   * @param {object} options — mesmos campos do wrapAWS (region default: "eastus2")
+   */
+  static wrapAzure(client, options = {}) {
+    const { apiKey, product, team, region = "eastus2", endpoint, debug = false } = options;
+    if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
+
+    const name = client?.constructor?.name || "";
+    const blobKind   = AZURE_BLOB_KIND[name];
+    const cosmosKind = AZURE_COSMOS_KIND[name];
+    if (!blobKind && !cosmosKind) {
+      // Aviso incondicional (não só em debug): sob bundler com mangling de nome
+      // de classe isto vira no-op, e um SDK que silenciosamente não coleta nada
+      // é pior que um que erra o rótulo. O wrapAWS degrada pra service:"unknown"
+      // justamente porque o gate dele é estrutural, não por nome.
+      console.warn(
+        `[CloudBroker] wrapAzure: client não reconhecido (${name || "sem construtor"}) — ` +
+        `nenhum custo será rastreado. Passe o client original do @azure/storage-blob ou @azure/cosmos.`,
+      );
+      return client;
+    }
+
+    if (client.__cbWrapped) {
+      console.warn("[CloudBroker] wrapAzure: este client já foi embrulhado — ignorando a segunda chamada.");
+      return client;
+    }
+
+    const cb  = new CloudBrokerClient({ apiKey, cloudEndpoint: endpoint, debug });
+    const env = { cb, product, team, region, debug };
+    return blobKind
+      ? CloudBrokerCloud.#wrapBlobNode(client, env)
+      : CloudBrokerCloud.#wrapCosmosNode(client, env, cosmosKind);
+  }
+
+  // ── Azure: helpers compartilhados ─────────────────────────────────────────
+
+  /**
+   * Extrai cbLabel/cbProduct/cbTeam do objeto de options NATIVO do método.
+   *
+   * Só olha a partir de `optIdx` — a posição onde o options bag pode
+   * legalmente começar naquele método. Isso é o que impede tocar num
+   * argumento de DADO do cliente: em `items.create(doc, options)` o `doc`
+   * está no índice 0 e nunca é inspecionado, então um documento que por
+   * acaso tenha um campo `cbLabel` é gravado intacto no Cosmos.
+   * Também nunca remove o argumento — devolve o objeto sem as chaves cb*,
+   * porque `setMetadata()` sem argumento apaga os metadados do blob.
+   */
+  static #extractCbArgs(args, optIdx) {
+    for (let i = Math.max(0, optIdx); i < args.length; i++) {
+      const a = args[i];
+      if (!isPlainObject(a)) continue;
+      if (a.cbLabel === undefined && a.cbProduct === undefined && a.cbTeam === undefined) continue;
+      const { cbLabel, cbProduct, cbTeam, ...rest } = a;
+      const cleaned = args.slice();
+      cleaned[i] = rest;
+      return { cbLabel, cbProduct, cbTeam, args: cleaned };
+    }
+    return { args };
+  }
+
+  /** Resolve label/product/team (explícito > contexto ALS > estático) e envia o evento. */
+  static #trackAzure(env, { service, operation, cbOpts = {}, requests = 1, bytesIn = 0, bytesOut = 0, requestCharge, latencyMs = 0 }) {
+    try {
+      const ctx = cbStore.getStore() || {};
+      const { costUSD, billingUnit } = estimateCloudCost({
+        provider: "azure", service, operation, requests, bytesOut, requestCharge, region: env.region,
+      });
+      env.cb.trackCloud({
+        provider:  "azure",
+        service,
+        operation,
+        product:   cbOpts.cbProduct || ctx.product || env.product || null,
+        team:      cbOpts.cbTeam    || ctx.team    || env.team    || null,
+        label:     cbOpts.cbLabel   || ctx.label   || null,
+        requests,
+        bytesIn,
+        bytesOut,
+        costUSD,
+        billingUnit,
+        latencyMs,
+        region:    env.region,
+      });
+    } catch (err) {
+      if (env.debug) console.warn("[CloudBroker] trackCloud error:", err.message);
+    }
+  }
+
+  /**
+   * Bytes de ENTRADA de um upload: só conta o argumento de corpo declarado
+   * (`bodyIdx`), nunca "a primeira string que aparecer" — em
+   * `uploadBlockBlob(nome, corpo, len)` a primeira string é o NOME do blob.
+   */
+  static #azureInputBytes(args, bodyIdx) {
+    if (bodyIdx == null) return 0;
+    const b = args[bodyIdx];
+    if (b == null) return 0;
+    if (typeof b === "string") return Buffer.byteLength(b);
+    if (Buffer.isBuffer(b)) return b.length;
+    if (b instanceof Uint8Array) return b.byteLength;
+    // Alguns métodos declaram o tamanho num argumento próprio (upload/stageBlock).
+    const len = args[bodyIdx + 1];
+    if (typeof len === "number" && Number.isFinite(len)) return len;
+    return 0; // streams/factories não são medidos
+  }
+
+  /**
+   * Bytes de SAÍDA — só para operações que de fato transferem conteúdo.
+   * `getProperties`/`exists` também devolvem `contentLength` (o tamanho do
+   * blob), mas não trafegam o blob: contá-lo cobrava egress de um GET de
+   * metadado, inflando o custo em ordens de grandeza.
+   */
+  static #azureOutputBytes(result) {
+    if (!result) return 0;
+    if (Buffer.isBuffer(result)) return result.length; // downloadToBuffer
+    if (typeof result.contentLength === "number") return result.contentLength;
+    return 0;
+  }
+
+  // ── Azure Blob Storage ────────────────────────────────────────────────────
+
+  static #wrapBlobNode(node, env) {
+    if (!node || typeof node !== "object" || node.__cbWrapped) return node;
+    if (!CloudBrokerCloud.#isMutable(node, env)) return node;
+
+    // Fábricas retornam sub-clients novos — embrulhados recursivamente.
+    for (const f of AZURE_BLOB_FACTORIES) {
+      if (typeof node[f] !== "function") continue;
+      const orig = node[f].bind(node);
+      CloudBrokerCloud.#safeAssign(node, f, (...args) => {
+        const sub = orig(...args);
+        try { return CloudBrokerCloud.#wrapBlobNode(sub, env); }
+        catch (err) {
+          if (env.debug) console.warn("[CloudBroker] wrap sub-client falhou:", err.message);
+          return sub; // instrumentação nunca pode custar o sub-client do cliente
+        }
+      }, env);
+    }
+
+    for (const [op, spec] of Object.entries(AZURE_BLOB_OPS)) {
+      if (typeof node[op] !== "function") continue;
+      const orig = node[op].bind(node);
+      CloudBrokerCloud.#safeAssign(node, op, async (...rawArgs) => {
+        // Fase 1 (pré-chamada): nada aqui pode impedir a chamada real.
+        let call = { args: rawArgs }, bytesIn = 0, start = Date.now();
+        try {
+          call = CloudBrokerCloud.#extractCbArgs(rawArgs, spec.optIdx);
+          bytesIn = CloudBrokerCloud.#azureInputBytes(call.args, spec.bodyIdx);
+        } catch (err) {
+          if (env.debug) console.warn("[CloudBroker] pré-tracking falhou:", err.message);
+          call = { args: rawArgs };
+        }
+
+        // Fase 2: a ÚNICA coisa que pode lançar para o cliente.
+        const result = await orig(...call.args);
+
+        // Fase 3 (pós-chamada): a operação já aconteceu no Azure — daqui pra
+        // frente uma exceção nossa faria o cliente tratar como falha e
+        // retentar, gerando escrita duplicada.
+        try {
+          CloudBrokerCloud.#trackAzure(env, {
+            service: "blob", operation: op,
+            cbOpts: { cbLabel: call.cbLabel, cbProduct: call.cbProduct, cbTeam: call.cbTeam },
+            bytesIn,
+            bytesOut: spec.transfers ? CloudBrokerCloud.#azureOutputBytes(result) : 0,
+            latencyMs: Date.now() - start,
+          });
+        } catch (err) {
+          if (env.debug) console.warn("[CloudBroker] pós-tracking falhou:", err.message);
+        }
+        return result;
+      }, env);
+    }
+
+    // list* devolvem PagedAsyncIterableIterator LAZY — nenhum HTTP acontece na
+    // chamada. Rastrear aqui emitia custo de uma operação que podia nunca
+    // existir; o evento sai quando a página é de fato buscada.
+    for (const op of AZURE_BLOB_ITERATOR_OPS) {
+      if (typeof node[op] !== "function") continue;
+      const orig = node[op].bind(node);
+      CloudBrokerCloud.#safeAssign(node, op, (...rawArgs) => {
+        let call = { args: rawArgs };
+        try { call = CloudBrokerCloud.#extractCbArgs(rawArgs, 0); }
+        catch { call = { args: rawArgs }; }
+        const iterator = orig(...call.args);
+        try {
+          return CloudBrokerCloud.#wrapPagedIterator(iterator, {
+            service: "blob", operation: op, env,
+            cbOpts: { cbLabel: call.cbLabel, cbProduct: call.cbProduct, cbTeam: call.cbTeam },
+          });
+        } catch (err) {
+          if (env.debug) console.warn("[CloudBroker] wrap iterator falhou:", err.message);
+          return iterator;
+        }
+      }, env);
+    }
+
+    CloudBrokerCloud.#markWrapped(node);
+    return node;
+  }
+
+  // ── Azure Cosmos DB ───────────────────────────────────────────────────────
+
+  /**
+   * @param {"client"|"database"|"container"|"item"} kind — o tipo do nó.
+   *   Necessário porque `Database` e `Container` do @azure/cosmos TAMBÉM
+   *   expõem read/replace/delete (control-plane, sobre a própria definição do
+   *   banco/container). Sem discriminar, um `database("x").read()` saía
+   *   rotulado como `item.read` — operação errada numa tela cujo propósito é
+   *   dizer qual trecho de código gasta.
+   */
+  static #wrapCosmosNode(node, env, kind) {
+    if (!node || typeof node !== "object" || node.__cbWrapped) return node;
+    if (!CloudBrokerCloud.#isMutable(node, env)) return node;
+
+    const childKind = { client: "database", database: "container", container: "item" };
+    for (const [f, next] of [["database", "database"], ["container", "container"], ["item", "item"]]) {
+      if (typeof node[f] !== "function") continue;
+      if (childKind[kind] !== next) continue; // só a fábrica que faz sentido pro nó atual
+      const orig = node[f].bind(node);
+      CloudBrokerCloud.#safeAssign(node, f, (...args) => {
+        const sub = orig(...args);
+        try { return CloudBrokerCloud.#wrapCosmosNode(sub, env, next); }
+        catch (err) {
+          if (env.debug) console.warn("[CloudBroker] wrap sub-client falhou:", err.message);
+          return sub;
+        }
+      }, env);
+    }
+
+    // read/replace/delete/patch existem em item, container E database — o
+    // prefixo da operação vem do tipo do nó, não do nome do método.
+    for (const [op, spec] of Object.entries(AZURE_COSMOS_NODE_OPS)) {
+      if (typeof node[op] !== "function") continue;
+      const orig = node[op].bind(node);
+      CloudBrokerCloud.#safeAssign(node, op, CloudBrokerCloud.#cosmosAsyncOp(orig, `${kind}.${op}`, env, spec.optIdx), env);
+    }
+
+    // Só Container tem .items
+    const items = node.items;
+    if (kind === "container" && items && typeof items === "object" && !items.__cbWrapped) {
+      for (const [op, spec] of Object.entries(AZURE_COSMOS_ITEMS_OPS)) {
+        if (typeof items[op] !== "function") continue;
+        const orig = items[op].bind(items);
+        CloudBrokerCloud.#safeAssign(items, op, CloudBrokerCloud.#cosmosAsyncOp(orig, `items.${op}`, env, spec.optIdx), env);
+      }
+      for (const [op, spec] of Object.entries(AZURE_COSMOS_ITEMS_ITERATOR_OPS)) {
+        if (typeof items[op] !== "function") continue;
+        const orig = items[op].bind(items);
+        CloudBrokerCloud.#safeAssign(items, op, (...rawArgs) => {
+          let call = { args: rawArgs };
+          try { call = CloudBrokerCloud.#extractCbArgs(rawArgs, spec.optIdx); }
+          catch { call = { args: rawArgs }; }
+          const iterator = orig(...call.args);
+          try {
+            return CloudBrokerCloud.#wrapCosmosIterator(iterator, `items.${op}`, {
+              cbLabel: call.cbLabel, cbProduct: call.cbProduct, cbTeam: call.cbTeam,
+            }, env);
+          } catch (err) {
+            if (env.debug) console.warn("[CloudBroker] wrap iterator falhou:", err.message);
+            return iterator;
+          }
+        }, env);
+      }
+      CloudBrokerCloud.#markWrapped(items);
+    }
+
+    CloudBrokerCloud.#markWrapped(node);
+    return node;
+  }
+
+  /** Embrulha uma operação async do Cosmos — lê o requestCharge (RUs) real da resposta. */
+  static #cosmosAsyncOp(orig, operation, env, optIdx) {
+    return async (...rawArgs) => {
+      let call = { args: rawArgs }, start = Date.now();
+      try { call = CloudBrokerCloud.#extractCbArgs(rawArgs, optIdx); }
+      catch (err) {
+        if (env.debug) console.warn("[CloudBroker] pré-tracking falhou:", err.message);
+        call = { args: rawArgs };
+      }
+
+      const result = await orig(...call.args);
+
+      try {
+        CloudBrokerCloud.#trackAzure(env, {
+          service: "cosmosdb", operation,
+          cbOpts: { cbLabel: call.cbLabel, cbProduct: call.cbProduct, cbTeam: call.cbTeam },
+          requestCharge: readRequestCharge(result),
+          latencyMs: Date.now() - start,
+        });
+      } catch (err) {
+        if (env.debug) console.warn("[CloudBroker] pós-tracking falhou:", err.message);
+      }
+      return result;
+    };
+  }
+
+  /** Embrulha o QueryIterator do Cosmos — RUs reais por fetchAll/fetchNext. */
+  static #wrapCosmosIterator(iterator, operation, cbOpts, env) {
+    if (!iterator || typeof iterator !== "object" || iterator.__cbWrapped) return iterator;
+    for (const m of ["fetchAll", "fetchNext"]) {
+      if (typeof iterator[m] !== "function") continue;
+      const orig = iterator[m].bind(iterator);
+      iterator[m] = async (...args) => {
+        const start  = Date.now();
+        const result = await orig(...args);
+        try {
+          CloudBrokerCloud.#trackAzure(env, {
+            service: "cosmosdb", operation: `${operation}.${m}`, cbOpts,
+            requestCharge: readRequestCharge(result),
+            latencyMs: Date.now() - start,
+          });
+        } catch (err) {
+          if (env.debug) console.warn("[CloudBroker] pós-tracking falhou:", err.message);
+        }
+        return result;
+      };
+    }
+    // for-await direto (getAsyncIterator) não é instrumentado — fetchAll/
+    // fetchNext cobrem o uso comum do @azure/cosmos. Documentado no README.
+    CloudBrokerCloud.#markWrapped(iterator);
+    return iterator;
+  }
+
+  /**
+   * Embrulha um PagedAsyncIterableIterator (list* do Blob): emite 1 evento por
+   * página REALMENTE buscada via byPage(); no for-await direto o SDK pagina
+   * internamente e só dá pra observar a primeira busca — nesse caso emite 1
+   * evento (aproximação declarada no README).
+   */
+  static #wrapPagedIterator(iterator, { service, operation, env, cbOpts }) {
+    if (!iterator || typeof iterator !== "object" || iterator.__cbWrapped) return iterator;
+
+    const emit = (start) => {
+      try {
+        CloudBrokerCloud.#trackAzure(env, { service, operation, cbOpts, latencyMs: Date.now() - start });
+      } catch (err) {
+        if (env.debug) console.warn("[CloudBroker] pós-tracking falhou:", err.message);
+      }
+    };
+
+    if (typeof iterator.byPage === "function") {
+      const origByPage = iterator.byPage.bind(iterator);
+      iterator.byPage = (...args) => {
+        const pages = origByPage(...args);
+        try { return wrapAsyncIterable(pages, emit, false); } // 1 evento POR página
+        catch { return pages; }
+      };
+    }
+
+    // for-await direto / .next(): 1 evento na primeira busca de fato.
+    try { return wrapAsyncIterable(iterator, emit, true); }
+    catch { return iterator; }
+  }
+
+  /** defineProperty pode lançar em objeto congelado — nunca deve derrubar o cliente. */
+  static #markWrapped(node) {
+    try { Object.defineProperty(node, "__cbWrapped", { value: true, enumerable: false, configurable: true }); }
+    catch { /* objeto não extensível: segue sem marca (pior caso, re-wrap) */ }
+  }
+
+  /**
+   * O wrap funciona mutando o client in-place. Se o cliente congelou (ou selou)
+   * a instância, a atribuição lança — em strict mode, que é o caso de um módulo
+   * ES. Instrumentação nunca pode derrubar a aplicação dele: avisa e devolve o
+   * client original, sem rastrear.
+   */
+  static #isMutable(node, env) {
+    if (Object.isExtensible(node)) return true;
+    console.warn(
+      "[CloudBroker] wrapAzure: client congelado/não extensível — nenhum custo será rastreado " +
+      "neste client. Embrulhe a instância antes de congelá-la.",
+    );
+    return false;
+  }
+
+  /** Atribuição defensiva: propriedade não gravável não pode virar exceção. */
+  static #safeAssign(node, key, value, env) {
+    try { node[key] = value; return true; }
+    catch (err) {
+      if (env?.debug) console.warn(`[CloudBroker] não foi possível instrumentar ${key}:`, err.message);
+      return false;
+    }
+  }
   /** Detecta o serviço AWS pelo nome do construtor do client. */
   static #detectService(client) {
     const name = client?.constructor?.name || "";