fg-tracker-sdk 0.11.0 → 0.14.0

package/dist/pg.js

@@ -1,7 +1,8 @@
 import { AsyncResource } from 'node:async_hooks';
+import { errorMonitor } from 'node:events';
 import { performance } from 'node:perf_hooks';
 import { databaseHost } from './database.js';
-import { databaseErrorAttributes, sqlCommandText, sqlSpanFields } from './normalize.js';
+import { analyzeSqlCommands, databaseErrorAttributes, sqlSpanFields } from './normalize.js';
 import { MIN_POOL_WAIT_MS } from './pool-wait.js';
 const PATCHED = Symbol.for('fg-tracker.pg.patched');
 /** Marca usada pelo `stread-track-sdk` ≤ 0.3: evita instrumentar duas vezes quando as duas versões convivem. */
@@ -10,8 +11,13 @@ const CLIENT_PATCHED = Symbol.for('fg-tracker.pg.clientPatched');
 function extractSql(arg) {
     if (typeof arg === 'string')
         return arg;
-    if (typeof arg === 'object' && arg !== null && typeof arg.text === 'string') {
-        return arg.text;
+    if (typeof arg === 'object' && arg !== null) {
+        if (typeof arg.text === 'string')
+            return arg.text;
+        // `pg-query-stream`: o texto fica no cursor interno.
+        const cursor = arg.cursor;
+        if (typeof arg.submit === 'function' && typeof cursor?.text === 'string')
+            return cursor.text;
     }
     return null;
 }
@@ -33,104 +39,205 @@ function recordDbError(span, err) {
     for (const [key, value] of Object.entries(databaseErrorAttributes(err)))
         span.setAttribute(key, value);
 }
+function isSubmittable(value) {
+    return typeof value === 'object' && value !== null && typeof value.submit === 'function';
+}
+/** Callback da aplicação no contexto de quem enviou a query, com o `this` que o `pg` lhe dá. */
+function bindCallback(cb, before) {
+    return AsyncResource.bind(function fgTrackerQueryCallback(...values) {
+        before(values);
+        return Reflect.apply(cb, this, values);
+    });
+}
 /**
  * Troca o callback da query, venha ele no último argumento (`query(text, values, cb)`) ou no
- * objeto de configuração (`query({ text, callback })`, que o `pg` também aceita), pelo devolvido por
- * `wrap`. O objeto do usuário não é alterado (vai uma cópia). `false` quando não há callback.
+ * objeto de configuração (`query({ text, callback })`, que o `pg` também aceita), pelo que avisa
+ * `finish` antes de chamá-lo. O objeto do usuário não é alterado (vai uma cópia). `false` quando não
+ * há callback.
  */
-function wrapCallback(args, wrap, 
-/** `pool.query` ignora `config.callback` (devolve Promise): só o `Client` o usa. */
-configCallback) {
+function wrapCallback(args, finish, configCallback) {
+    const before = (values) => finish(values[0], values[1]);
     const last = args[args.length - 1];
     if (typeof last === 'function') {
-        args[args.length - 1] = wrap(last);
+        args[args.length - 1] = bindCallback(last, before);
         return true;
     }
     const config = args[0];
     // `query(config)` ou `query(config, values)`: com uma função em outro argumento, ela vence (o `pg` faz igual).
     const onlyValues = args.length === 1 || (args.length === 2 && typeof args[1] !== 'function');
-    if (configCallback && onlyValues && config && typeof config === 'object' && typeof config.submit !== 'function') {
+    if (configCallback && onlyValues && config && typeof config === 'object') {
         const callback = config.callback;
         if (typeof callback === 'function') {
-            args[0] = { ...config, callback: wrap(callback) };
+            args[0] = { ...config, callback: bindCallback(callback, before) };
             return true;
         }
     }
     return false;
 }
 /**
- * Executa uma query dentro de um span `db.query` (nome = SQL normalizado; `rows`, fingerprint,
- * semconv). Suporta as assinaturas (text), (config), (text, values), (text, cb) e (text, values, cb).
- * `onSettled` roda depois da query, com o erro (ou `undefined`) e o resultado.
+ * Observa um Submittable até o fim real, sem mudar o que a aplicação vê. Avisa `finish` uma vez, no
+ * primeiro destes sinais:
+ * - o callback do objeto (`new pg.Query(text, cb)`) ou o passado em `client.query(q, cb)`: no erro, o
+ *   `pg` chama o callback e não emite `error`;
+ * - `handleReadyForQuery`/`handleError`, que o `pg` chama no objeto ativo (o fim no servidor e o
+ *   erro, inclusive o do cursor sem listener de `error`, que não emite nada);
+ * - os eventos `end`, `close` (stream destruído antes do fim) e o erro por `events.errorMonitor`,
+ *   que é avisado antes dos listeners e não conta como um: sem listener da aplicação, o erro continua
+ *   sendo lançado como sem o SDK.
+ * Tudo o que foi instalado sai no primeiro sinal.
  */
-function runQuery(core, original, args, sql, baseAttributes, parent, onStart, onSettled, 
-/** Query de um `Client`: o callback pode vir em `config.callback`. */
-clientQuery = false) {
-    const fields = sqlSpanFields(sql);
-    const span = core.startSpan('db.query', fields.name, { rows: null, ...baseAttributes, ...fields.attributes }, parent);
-    onStart?.(span);
-    const settle = (err, result) => {
-        if (err)
-            recordDbError(span, err);
-        else
-            span.setAttribute('rows', rowCount(result));
-        span.end();
+function observeSubmittable(q, args, finish) {
+    const undo = [];
+    const done = (err, result) => {
+        for (const step of undo.splice(0)) {
+            try {
+                step();
+            }
+            catch {
+                /* nada a desfazer */
+            }
+        }
+        finish(err, result);
+    };
+    const before = (values) => done(values[0], values[1]);
+    if (typeof q.callback === 'function') {
+        // Fica no objeto: no erro, o `pg` chama o callback depois do `handleError` (o primeiro sinal), e
+        // ele precisa rodar no contexto de quem enviou. Chamado de novo, só repassa.
+        q.callback = bindCallback(q.callback, before);
+    }
+    else if (typeof args[1] === 'function') {
+        args[1] = bindCallback(args[1], before);
+    }
+    else if (typeof args[2] === 'function') {
+        args[2] = bindCallback(args[2], before);
+    }
+    const hook = (name, when) => {
+        const original = q[name];
+        if (typeof original !== 'function')
+            return;
+        const own = Object.hasOwn(q, name);
+        const hooked = function fgTrackerSubmittableHook(...values) {
+            if (when === 'before')
+                done(values[0], undefined);
+            try {
+                return Reflect.apply(original, this, values);
+            }
+            finally {
+                if (when === 'after')
+                    done(undefined, q._results ?? q._result);
+            }
+        };
+        q[name] = hooked;
+        undo.push(() => {
+            if (q[name] !== hooked)
+                return;
+            if (own)
+                q[name] = original;
+            else
+                delete q[name];
+        });
+    };
+    hook('handleError', 'before');
+    hook('handleReadyForQuery', 'after');
+    if (typeof q.once === 'function' && typeof q.removeListener === 'function') {
+        const onEnd = (result) => done(undefined, result);
+        const onError = (err) => done(err, undefined);
+        const onClose = () => done(undefined, undefined);
+        q.once('end', onEnd);
+        q.once(errorMonitor, onError);
+        q.once('close', onClose);
+        undo.push(() => {
+            q.removeListener('end', onEnd);
+            q.removeListener(errorMonitor, onError);
+            q.removeListener('close', onClose);
+        });
+    }
+}
+/**
+ * Chama `original(...args)` e avisa `onFinish` uma única vez, quando a query termina de verdade:
+ * callback (nos argumentos ou em `config.callback`), Promise, Submittable ({@link observeSubmittable})
+ * ou, num client compatível que devolve outra coisa, na hora. `register` guarda a finalização de
+ * quem ainda está em voo (a conexão encerrada termina o que sobrar).
+ */
+function callTracked(original, args, onFinish, 
+/** `pool.query` ignora `config.callback` (devolve Promise): só o `Client` o usa. */
+configCallback, register, 
+/**
+ * Executa a chamada ao `pg` (o `runQuery` a põe dentro do span da query, para o que o `pg` fizer
+ * nela). Os callbacks e a continuação da Promise são ligados antes, fora dela: rodam no contexto de
+ * quem enviou a query, nunca no do span da query, que já terá fechado.
+ */
+invoke = (call) => call()) {
+    let finished = false;
+    let unregister;
+    const finish = (err, result) => {
+        if (finished)
+            return;
+        finished = true;
+        unregister?.();
         try {
-            onSettled?.(err, result);
+            onFinish(err, result);
         }
         catch {
-            /* acompanhamento de transação nunca quebra a query */
+            /* acompanhamento nunca quebra a query */
         }
     };
+    const submittable = isSubmittable(args[0]) ? args[0] : null;
     // O pg chama o callback no contexto do socket (o de quem abriu a conexão): volta ao de quem
     // enviou a query, para a finalização e o código do usuário.
-    const withCallback = wrapCallback(args, (cb) => AsyncResource.bind((err, result) => {
-        settle(err, result);
-        cb(err, result);
-    }), clientQuery);
-    if (withCallback)
-        return core.runInSpan(span, () => original(...args));
+    const withCallback = submittable ? false : wrapCallback(args, finish, configCallback);
+    if (submittable)
+        observeSubmittable(submittable, args, finish);
+    if (submittable || withCallback)
+        unregister = register?.(finish);
     let out;
     try {
-        out = core.runInSpan(span, () => original(...args));
+        out = invoke(() => original(...args));
     }
     catch (err) {
-        settle(err, undefined);
+        finish(err, undefined);
         throw err;
     }
+    if (submittable || withCallback)
+        return out;
     if (out && typeof out.then === 'function') {
         return out.then((result) => {
-            settle(undefined, result);
+            finish(undefined, result);
             return result;
         }, (err) => {
-            settle(err, undefined);
+            finish(err, undefined);
             throw err;
         });
     }
-    settle(undefined, out);
+    finish(undefined, out);
     return out;
 }
-/** BEGIN/START TRANSACTION abrem; COMMIT/END fecham; ROLLBACK/ABORT (não `ROLLBACK TO`) desfazem. */
-function transactionCommand(sql) {
-    const head = sql.replace(/^\s*(?:--[^\n]*\n\s*|\/\*[\s\S]*?\*\/\s*)*/, '').slice(0, 40).toLowerCase();
-    if (/^(begin|start\s+transaction)\b/.test(head))
-        return 'begin';
-    if (/^(commit|end)\b/.test(head) && !/^commit\s+prepared\b/.test(head))
-        return 'commit';
-    if (/^(rollback|abort)\b/.test(head) && !/^rollback\s+(to|prepared)\b/.test(head))
-        return 'rollback';
-    return null;
-}
-/** Comandos do texto (separados por `;`, ignorando literais e comentários) e os de transação, em ordem. */
-function sqlStatements(sql) {
-    const statements = sqlCommandText(sql).split(';').filter((statement) => statement.trim());
-    const transaction = [];
-    for (const statement of statements) {
-        const command = transactionCommand(statement);
-        if (command)
-            transaction.push(command);
-    }
-    return { count: statements.length, transaction };
+/**
+ * Executa uma query dentro de um span `db.query` (nome = SQL normalizado; `rows`, fingerprint,
+ * semconv). Suporta as assinaturas (text), (config), (text, values), (text, cb), (text, values, cb)
+ * e Submittables; o span fecha no fim real da query.
+ */
+function runQuery(core, original, args, sql, baseAttributes, options = {}) {
+    const fields = sqlSpanFields(sql, 'postgresql');
+    const span = core.startSpan('db.query', fields.name, { rows: null, ...baseAttributes, ...fields.attributes }, options.parent);
+    options.onStart?.(span);
+    const settle = (err, result) => {
+        if (err)
+            recordDbError(span, err);
+        else
+            span.setAttribute('rows', rowCount(result));
+        try {
+            options.beforeEnd?.(err, result, span);
+        }
+        catch {
+            /* atributos são best-effort */
+        }
+        span.end();
+        options.onSettled?.(err, result);
+    };
+    // Só a chamada ao `pg` roda no span da query; o callback da aplicação volta ao contexto de quem
+    // enviou (a raiz dela, com as decisões dela), como antes da 0.14.
+    return callTracked(original, args, settle, options.clientQuery === true, options.register, (call) => core.runInSpan(span, call));
 }
 /**
  * Estado da transação no servidor depois da última resposta (`ReadyForQuery`): `I` fora de
@@ -156,6 +263,17 @@ const SYNTAX_ERROR = '42601';
 function errorCode(err) {
     return typeof err === 'object' && err !== null ? err.code : undefined;
 }
+/**
+ * Erro de sintaxe da análise do texto inteiro (nada rodou). O 42601 de um `EXECUTE` dinâmico em
+ * PL/pgSQL acontece em tempo de execução, depois do que veio antes, e o servidor o marca com o
+ * contexto (`where`) e a query interna (`internalQuery`).
+ */
+function isParseError(err) {
+    if (errorCode(err) !== SYNTAX_ERROR || typeof err !== 'object' || err === null)
+        return false;
+    const { where, internalQuery } = err;
+    return !where && !internalQuery;
+}
 /** Texto de um prepared statement executado só pelo nome, como o `pg` o guardou na conexão. */
 function preparedText(client, config) {
     const name = config && typeof config === 'object' ? config.name : undefined;
@@ -174,36 +292,18 @@ function answeredCommand(result) {
     const last = Array.isArray(result) ? result[result.length - 1] : result;
     return last?.command;
 }
-/**
- * Acompanha uma query sem SQL em texto (prepared statement executado só pelo nome,
- * `client.query({ name })`): sem span, só para a transação seguir o estado do servidor.
- */
-function observeQuery(original, args, onSettled) {
-    const settle = (err, result) => {
-        try {
-            onSettled(err, result);
-        }
-        catch {
-            /* acompanhamento nunca quebra a query */
-        }
-    };
-    const withCallback = wrapCallback(args, (cb) => AsyncResource.bind((err, result) => {
-        settle(err, result);
-        cb(err, result);
-    }), true);
-    if (withCallback)
-        return original(...args);
-    const out = original(...args);
-    if (out && typeof out.then === 'function') {
-        return out.then((result) => {
-            settle(undefined, result);
-            return result;
-        }, (err) => {
-            settle(err, undefined);
-            throw err;
-        });
-    }
-    return out;
+/** Texto desconhecido (nome preparado fora desta conexão): pode encerrar a transação. */
+const UNKNOWN_TEXT = { count: 1, transaction: [], closes: true, ends: true, startsWithBegin: false };
+/** Contexto que a transação aceita como dona: mesma execução e mesmas decisões de amostragem e exclusão. */
+function sameExecution(core, sender, tx) {
+    if (core.localRootOfContext(sender) === tx.localRootId)
+        return true;
+    // Raiz de mensagem aberta pelo `trackMessage` dentro da raiz da transação (lote com BEGIN antes do laço).
+    const execution = core.executionRootOfContext(sender);
+    return execution !== undefined && execution === tx.localRootId;
+}
+function sameDecisions(sender, tx) {
+    return (sender.sampled !== false) === tx.sampled && (sender.ignored === true) === tx.ignored;
 }
 function poolStats(pool) {
     const out = {};
@@ -222,8 +322,18 @@ function poolStats(pool) {
  * - `pool.connect()`: span `custom` `pg connect` com a espera por conexão (`db.poolWaitMs`) e a
  *   ocupação do pool; o client devolvido também gera spans `db.query`;
  * - transação num client (`BEGIN` … `COMMIT`/`ROLLBACK`): span `custom` `pg transaction`, pai das
- *   queries dela, com `db.transaction.outcome` (`commit`, `rollback` ou `released_open` quando o
- *   client volta ao pool com a transação aberta).
+ *   queries dela, com `db.transaction.outcome` (`commit`, `rollback`, `prepared` ou `released_open`
+ *   quando o client volta ao pool com a transação aberta).
+ *
+ * Quem é pai de uma query num client com transação aberta (CONTRATO.md §16.1):
+ * - a mesma execução que abriu a transação (mesma raiz local, ou a raiz de mensagem que o
+ *   `trackMessage` abriu dentro dela), com as mesmas decisões de amostragem e exclusão: a transação,
+ *   salvo com um COMMIT/ROLLBACK dela já a caminho;
+ * - outra execução (outra requisição, mesmo do mesmo trace distribuído): o próprio contexto, com as
+ *   próprias decisões; se rodar dentro da transação confirmada, leva `links` para ela e
+ *   `db.transaction.foreign: true`;
+ * - quem envia sem contexto: a transação só na janela confirmada pelo servidor (BEGIN respondido,
+ *   nenhum comando de encerramento em voo em nenhuma leitura do texto); fora dela, nenhum span.
  */
 export function instrumentPgPool(core, pool) {
     const target = pool;
@@ -241,7 +351,7 @@ export function instrumentPgPool(core, pool) {
     const stateOf = (client) => {
         let state = states.get(client);
         if (!state) {
-            state = { tx: null, internal: false, pending: 0, seq: 0, txSeq: 0, closingSeq: 0 };
+            state = { tx: null, queued: null, internal: false, seq: 0, inFlight: new Map() };
             states.set(client, state);
         }
         return state;
@@ -251,118 +361,198 @@ export function instrumentPgPool(core, pool) {
      * próprio pool. O span da query recebe a espera (`db.poolWaitMs`) em vez de um span `pg connect`.
      */
     let poolQuery = null;
-    const endTransaction = (state, outcome, err) => {
+    const finishSpan = (tx, outcome, err) => {
+        tx.span.setAttribute('db.transaction.outcome', outcome);
+        if (err)
+            recordDbError(tx.span, err);
+        tx.span.end();
+    };
+    /**
+     * Fecha a transação atual. Pelo fim observado no servidor (`promote`), o BEGIN que esperava na fila
+     * passa a ser a transação atual (ainda sem confirmação); no release e na conexão encerrada, ele
+     * fecha junto.
+     */
+    const endTransaction = (state, outcome, err, promote = false) => {
         const tx = state.tx;
-        if (!tx)
+        if (tx) {
+            state.tx = null;
+            finishSpan(tx, outcome, err);
+        }
+        const queued = state.queued;
+        if (!queued)
             return;
-        state.tx = null;
-        state.closingSeq = 0;
-        tx.setAttribute('db.transaction.outcome', outcome);
-        if (err)
-            recordDbError(tx, err);
-        tx.end();
+        state.queued = null;
+        if (promote)
+            state.tx = queued;
+        else
+            finishSpan(queued, outcome);
     };
     /**
-     * Fecha ou abre o span da transação depois de uma query. Fonte primária: o estado que o servidor
-     * devolve no `ReadyForQuery` (`getTransactionStatus()`, nas versões do `pg` que o têm). Plano B, para drivers sem o
-     * método e para erros (o callback de erro do `pg` roda antes do `ReadyForQuery`, com o estado
-     * anterior): todos os comandos de transação do texto, em ordem.
+     * Comando de encerramento de `tx` ainda sem fim real: enviado depois do BEGIN dela ou no mesmo
+     * envio (`BEGIN; …; COMMIT`).
      */
-    const settleTransaction = (client, state, sql, err, result, 
-    /** Abre o span da transação no contexto de quem enviou a query; `null` fora de um trace. */
+    const closingAfter = (state, tx, which) => {
+        if (!tx)
+            return false;
+        for (const [seq, query] of state.inFlight)
+            if (seq >= tx.seq && query[which])
+                return true;
+        return false;
+    };
+    const closingInFlight = (state, which) => closingAfter(state, state.tx, which);
+    /**
+     * Fecha, abre ou confirma a transação depois do fim real de uma query. Fonte primária: o estado
+     * que o servidor devolve no `ReadyForQuery` (`getTransactionStatus()` ou o evento da conexão). Sem
+     * estado nenhum (client compatível), os comandos de transação do texto, em ordem.
+     */
+    const settleTransaction = (client, state, analysis, err, result, 
+    /** Abre o span da transação no contexto de quem enviou a query; `null` sem contexto. */
     startTx, 
     /** O span da transação foi aberto por esta query (o texto começa com BEGIN). */
     openedHere, 
-    /** Ordem de envio desta query (`state.seq` no envio). */
-    seq) => {
-        // Query enviada antes do BEGIN que abriu a transação atual (fila do `pg`): o estado que a
-        // resposta dela traz é de antes da transação e não a fecha.
-        if (state.tx && seq < state.txSeq)
-            return;
-        const open = (start) => {
-            state.tx = start();
-            state.txSeq = seq;
-        };
-        const outcomeFor = (last) => {
-            if (err)
-                return last === 'commit' ? 'commit_failed' : last === 'begin' ? 'begin_failed' : 'rollback';
+    /** Ordem de envio desta query. */
+    seq, 
+    /** Fim real: a query sai da lista de em voo (no erro antes do `ReadyForQuery`, só quando ele chega). */
+    release) => {
+        const failed = err !== undefined && err !== null;
+        const last = analysis.transaction[analysis.transaction.length - 1] ?? null;
+        const outcomeFor = () => {
+            if (failed)
+                return last === 'commit' ? 'commit_failed' : last === 'begin' ? 'begin_failed' : last === 'prepare' ? 'prepare_failed' : 'rollback';
             const answered = answeredCommand(result);
-            return answered === 'ROLLBACK' || (answered !== 'COMMIT' && last === 'rollback') ? 'rollback' : 'commit';
+            if (answered === 'ROLLBACK')
+                return 'rollback';
+            if (last === 'prepare')
+                return 'prepared';
+            return answered !== 'COMMIT' && last === 'rollback' ? 'rollback' : 'commit';
+        };
+        const fromServer = (status) => {
+            // Query enviada antes do BEGIN que abriu a transação atual (fila do `pg`): o estado que a
+            // resposta dela traz é de antes da transação e não a fecha.
+            if (state.tx && seq < state.tx.seq)
+                return;
+            if (status === 'I') {
+                if (state.tx)
+                    endTransaction(state, outcomeFor(), err, true);
+            }
+            else if (state.tx) {
+                state.tx.confirmed = true;
+            }
+            else if (startTx) {
+                // `SELECT 1; BEGIN`, BEGIN preparado: a transação existe a partir desta resposta.
+                state.tx = { span: startTx(), seq, confirmed: true };
+            }
         };
-        const statements = sqlStatements(sql);
-        const last = statements.transaction[statements.transaction.length - 1] ?? null;
         const status = serverTransactionStatus(client, state.observedStatus);
         // Erro com o `ReadyForQuery` ainda por chegar: o estado do servidor é o de antes da query.
-        const stale = err !== undefined && err !== null && client.readyForQuery === false;
+        const stale = failed && client.readyForQuery === false;
         const connection = client.connection;
-        const canAwaitServer = stale && typeof connection?.once === 'function';
-        if (status !== undefined && !stale) {
-            if (status === 'I' && state.tx)
-                endTransaction(state, outcomeFor(last), err);
-            else if (status !== 'I' && !state.tx && startTx)
-                open(startTx); // `SELECT 1; BEGIN`, BEGIN preparado
-            return;
-        }
-        if (statements.transaction.length > 0) {
-            if (!err) {
-                // Sem erro, todos os comandos rodaram: vale o efeito do último.
-                if (last === 'begin') {
-                    if (!state.tx && startTx)
-                        open(startTx);
+        if (stale && (state.tx === null || seq >= state.tx.seq)) {
+            // O próprio erro já diz o estado em dois casos, sem esperar a resposta (a próxima query de quem
+            // recebeu o erro sai antes dela): o texto recusado na análise não rodou nada, e o único comando,
+            // um COMMIT/ROLLBACK/PREPARE TRANSACTION que falhou, tirou a sessão da transação.
+            if (isParseError(err)) {
+                release();
+                if (openedHere && state.tx === openedHere)
+                    endTransaction(state, 'begin_failed', err, true);
+                else if (openedHere && state.queued === openedHere) {
+                    state.queued = null;
+                    finishSpan(openedHere, 'begin_failed', err);
                 }
-                else if (state.tx) {
-                    endTransaction(state, outcomeFor(last), err);
-                }
-            }
-            else if (errorCode(err) === SYNTAX_ERROR) {
-                // Erro de sintaxe: o Postgres analisa o texto inteiro antes de executar, então nenhum
-                // comando rodou e o estado do servidor é o de antes. Só a transação que esta query abriu
-                // (o BEGIN dela) deixa de existir.
-                if (openedHere && state.tx)
-                    endTransaction(state, 'begin_failed', err);
-            }
-            else if (last === 'commit' || last === 'rollback') {
-                // COMMIT que falha termina a transação; com vários comandos não se sabe qual falhou, e
-                // fechar é o lado seguro (mantida aberta, a próxima requisição herdaria o trace).
-                if (state.tx)
-                    endTransaction(state, outcomeFor(last), err);
+                return;
             }
-            else if (state.tx && statements.count === 1) {
-                endTransaction(state, 'begin_failed', err); // só `BEGIN`, e ele falhou
+            if (analysis.count === 1 && (last === 'commit' || last === 'rollback' || last === 'prepare') && state.tx) {
+                release();
+                endTransaction(state, outcomeFor(), err, true);
+                return;
             }
-            // Outro erro num texto que termina com BEGIN: o BEGIN rodou e o comando seguinte falhou, então a
-            // transação está abortada (`E`) e continua aberta até o ROLLBACK.
         }
-        // Erro com o servidor ainda por responder: confere o estado quando o `ReadyForQuery` chegar
-        // (o estado observado é atualizado na frente de qualquer listener).
-        if (canAwaitServer) {
-            const current = state.tx;
+        if (stale && typeof connection?.once === 'function') {
+            // A decisão espera o estado do servidor (L2): `SELECT 1/0; COMMIT` deixa a transação abortada
+            // aberta, e um 42601 do EXECUTE dinâmico não quer dizer que o BEGIN não rodou. Até lá a query
+            // continua em voo (protege a janela de quem vem depois).
             try {
                 connection.once('readyForQuery', () => {
-                    // Só a transação desta query: um BEGIN enviado depois já abriu outra.
-                    if (!current || state.tx !== current)
-                        return;
+                    release();
                     const now = serverTransactionStatus(client, state.observedStatus);
-                    if (now === 'I')
-                        endTransaction(state, outcomeFor(last), err);
+                    if (now !== undefined)
+                        fromServer(now);
+                    else if (openedHere && state.tx === openedHere)
+                        endTransaction(state, 'begin_failed', err, true);
                 });
+                return;
             }
             catch {
-                /* sem o evento, fica o que o texto decidiu */
+                /* sem o evento, decide agora pelo texto */
             }
         }
+        release();
+        if (openedHere && state.queued === openedHere) {
+            // O BEGIN da fila respondeu antes de a transação anterior fechar: rodou dentro dela e não abriu
+            // outra (o servidor só avisa). A transação da fila fecha sem ter existido.
+            state.queued = null;
+            finishSpan(openedHere, 'begin_failed', failed ? err : undefined);
+        }
+        if (status !== undefined && !stale) {
+            fromServer(status);
+            return;
+        }
+        if (state.tx && seq < state.tx.seq)
+            return;
+        if (!failed) {
+            // Sem erro, todos os comandos rodaram: vale o efeito do último.
+            if (last === 'begin' || last === 'chain') {
+                if (state.tx)
+                    state.tx.confirmed = true;
+                else if (startTx)
+                    state.tx = { span: startTx(), seq, confirmed: true };
+            }
+            else if (last && state.tx) {
+                endTransaction(state, outcomeFor(), err, true);
+            }
+            else if (state.tx && openedHere === state.tx) {
+                state.tx.confirmed = true;
+            }
+            return;
+        }
+        if (!state.tx || analysis.transaction.length === 0)
+            return;
+        if (errorCode(err) === SYNTAX_ERROR) {
+            // Erro de sintaxe: o Postgres analisa o texto inteiro antes de executar, então nenhum
+            // comando rodou e o estado do servidor é o de antes. Só a transação que esta query abriu
+            // (o BEGIN dela) deixa de existir.
+            if (openedHere && state.tx === openedHere)
+                endTransaction(state, 'begin_failed', err, true);
+        }
+        else if (last === 'commit' || last === 'rollback' || last === 'prepare') {
+            // COMMIT que falha termina a transação; com vários comandos não se sabe qual falhou, e
+            // fechar é o lado seguro (mantida aberta, a próxima requisição herdaria o trace).
+            endTransaction(state, outcomeFor(), err, true);
+        }
+        else if (analysis.count === 1 && last === 'begin') {
+            endTransaction(state, 'begin_failed', err, true); // só `BEGIN`, e ele falhou
+        }
+        // Outro erro num texto que termina com BEGIN: o BEGIN rodou e o comando seguinte falhou, então a
+        // transação está abortada (`E`) e continua aberta até o ROLLBACK (sem confirmação do servidor).
     };
     const patchClient = (client) => {
         if (!client || typeof client.query !== 'function' || client[CLIENT_PATCHED])
             return;
         client[CLIENT_PATCHED] = true;
         // Conexão encerrada (`client.end()`, queda, término pelo servidor): o Postgres desfaz a
-        // transação aberta; o span fecha junto, senão ficaria retido no tracker para sempre.
+        // transação aberta; o span fecha junto, senão ficaria retido no tracker para sempre. O que ainda
+        // estava em voo (cursor nunca fechado) termina aqui.
         if (typeof client.once === 'function') {
             try {
                 client.once('end', () => {
                     const state = states.get(client);
-                    if (state?.tx)
+                    if (!state)
+                        return;
+                    const closed = new Error('Connection terminated');
+                    for (const query of [...state.inFlight.values()])
+                        query.finish?.(closed, undefined);
+                    state.inFlight.clear();
+                    if (state.tx || state.queued)
                         endTransaction(state, 'connection_closed');
                 });
             }
@@ -370,9 +560,9 @@ export function instrumentPgPool(core, pool) {
                 /* sem o evento, a transação fecha pela próxima query ou pelo release */
             }
         }
+        const connection = client.connection;
         // Estado do servidor em cada `ReadyForQuery`, na frente do listener do próprio client (que
         // resolve a query): vale para as versões do `pg` sem `getTransactionStatus()`.
-        const connection = client.connection;
         if (typeof connection?.prependListener === 'function') {
             try {
                 connection.prependListener('readyForQuery', (msg) => {
@@ -385,6 +575,20 @@ export function instrumentPgPool(core, pool) {
                 /* sem o evento, fica o texto */
             }
         }
+        // `standard_conforming_strings` da sessão (início da conexão e cada SET): decide a leitura
+        // principal do texto. Com barra invertida no texto, as duas leituras protegem a janela.
+        if (typeof connection?.on === 'function') {
+            try {
+                connection.on('parameterStatus', (msg) => {
+                    const { parameterName, parameterValue } = (msg ?? {});
+                    if (parameterName === 'standard_conforming_strings')
+                        stateOf(client).standardConformingStrings = parameterValue === 'off' ? 'off' : 'on';
+                });
+            }
+            catch {
+                /* sem o evento, as duas leituras */
+            }
+        }
         const clientQuery = client.query.bind(client);
         client.query = function fgTrackerClientQuery(...args) {
             const state = stateOf(client);
@@ -392,7 +596,7 @@ export function instrumentPgPool(core, pool) {
                 return clientQuery(...args);
             // Rede de segurança: sem query em voo e com o servidor fora de transação, uma transação que
             // ainda conste aberta terminou por um caminho não observado; não pode virar pai desta query.
-            if (state.tx && state.pending === 0 && client.readyForQuery !== false && serverTransactionStatus(client, state.observedStatus) === 'I') {
+            if (state.tx && state.inFlight.size === 0 && client.readyForQuery !== false && serverTransactionStatus(client, state.observedStatus) === 'I') {
                 endTransaction(state, 'unobserved_end');
             }
             // Prepared statement executado só pelo nome: o texto é o que o `pg` guardou ao prepará-lo nesta
@@ -401,46 +605,91 @@ export function instrumentPgPool(core, pool) {
             // O contexto de quem envia a query: o callback do pg roda no contexto do socket, que pode ser
             // o da requisição que abriu a conexão.
             const sender = core.currentContext();
+            if (!state.tx && !state.queued && !sender)
+                return clientQuery(...args);
+            // Análise dos comandos de transação feita uma vez por query, para o envio e para a resposta (O1).
+            const analysis = sql === null ? UNKNOWN_TEXT : analyzeSqlCommands(sql, state.standardConformingStrings);
             const startTx = sender ? () => core.startSpan('custom', 'pg transaction', { ...baseAttributes, 'db.operation.name': 'transaction' }, sender) : null;
-            if (!sql) {
-                // Sem texto conhecido (client compatível, nome preparado fora desta conexão): sem span, mas um
-                // BEGIN, COMMIT ou ROLLBACK preparado abre ou termina a transação pelo estado do servidor.
-                if (!state.tx && !startTx)
-                    return clientQuery(...args);
-                const seq = ++state.seq;
-                state.pending += 1;
-                return observeQuery(clientQuery, args, (err, result) => {
-                    state.pending = Math.max(0, state.pending - 1);
-                    settleTransaction(client, state, '', err, result, startTx, false, seq);
-                });
-            }
-            const command = transactionCommand(sql);
             const seq = ++state.seq;
-            const openedHere = command === 'begin' && !state.tx && !!startTx;
-            if (openedHere) {
-                state.tx = startTx();
-                state.txSeq = seq;
-            }
-            // Com um COMMIT/ROLLBACK da transação já a caminho, esta query roda depois dele, fora dela.
-            const tx = state.tx && state.closingSeq === 0 ? state.tx : null;
-            const parent = tx ? tx.context() : core.currentContext();
-            if (!parent)
-                return clientQuery(...args);
-            // Inclusive no texto que abre e fecha a transação no mesmo envio (`BEGIN; …; COMMIT`).
-            if (tx) {
-                const statements = sqlStatements(sql);
-                const last = statements.transaction[statements.transaction.length - 1];
-                if (last === 'commit' || last === 'rollback')
-                    state.closingSeq = seq;
-            }
-            state.pending += 1;
-            return runQuery(core, clientQuery, args, sql, baseAttributes, parent, undefined, (err, result) => {
-                state.pending = Math.max(0, state.pending - 1);
-                settleTransaction(client, state, sql, err, result, startTx, openedHere, seq);
-                // Respondido sem fechar a transação (erro de sintaxe, por exemplo): ela continua sendo o pai.
-                if (state.closingSeq === seq)
-                    state.closingSeq = 0;
-            }, true);
+            const tx = state.tx;
+            let parent;
+            let foreign = null;
+            const queued = state.queued;
+            if (queued && sender && sameExecution(core, sender, queued.span) && sameDecisions(sender, queued.span)) {
+                // Atrás do BEGIN que esperava na fila: roda na transação que ele vai abrir, salvo com um
+                // COMMIT/ROLLBACK dela já a caminho (roda depois dele, fora dela).
+                parent = closingAfter(state, queued, 'ends') ? sender : queued.span.context();
+            }
+            else if (tx && sender && sameExecution(core, sender, tx.span) && sameDecisions(sender, tx.span)) {
+                // Com um COMMIT/ROLLBACK da transação já a caminho, esta query roda depois dele, fora dela.
+                parent = closingInFlight(state, 'ends') ? sender : tx.span.context();
+            }
+            else if (tx && tx.confirmed && !closingInFlight(state, 'closes')) {
+                // Dentro da janela confirmada pelo servidor: quem envia sem contexto roda na transação e fica
+                // sob ela; outra execução fica sob o próprio contexto, com o vínculo.
+                if (sender) {
+                    parent = sender;
+                    foreign = tx;
+                }
+                else {
+                    parent = tx.span.context();
+                }
+            }
+            else {
+                // Outra execução, ou ninguém, fora da janela (BEGIN sem resposta, encerramento em voo,
+                // dúvida): o próprio contexto; sem contexto, nenhum span (como antes do #38).
+                parent = sender;
+            }
+            let openedHere = null;
+            if (analysis.startsWithBegin && startTx && (!state.tx || (!state.queued && closingInFlight(state, 'ends')))) {
+                openedHere = { span: startTx(), seq, confirmed: false };
+                if (state.tx)
+                    state.queued = openedHere;
+                else
+                    state.tx = openedHere;
+                parent = openedHere.span.context();
+            }
+            const flight = { closes: analysis.closes, ends: analysis.ends };
+            state.inFlight.set(seq, flight);
+            const register = (finish) => {
+                flight.finish = finish;
+                return () => {
+                    flight.finish = undefined;
+                };
+            };
+            let released = false;
+            const release = () => {
+                if (released)
+                    return;
+                released = true;
+                state.inFlight.delete(seq);
+            };
+            const settle = (err, result) => settleTransaction(client, state, analysis, err, result, startTx, openedHere, seq, release);
+            if (!sql || !parent) {
+                // Sem texto conhecido ou sem pai: sem span, mas a transação segue o estado do servidor.
+                return callTracked(clientQuery, args, settle, true, register);
+            }
+            return runQuery(core, clientQuery, args, sql, baseAttributes, {
+                parent,
+                clientQuery: true,
+                register,
+                onSettled: settle,
+                onStart: (span) => {
+                    if (!foreign)
+                        return;
+                    span.setAttribute('links', [{ traceId: foreign.span.traceId, spanId: foreign.span.spanId }]);
+                    span.setAttribute('db.transaction.foreign', true);
+                },
+                beforeEnd: (err, _result, span) => {
+                    // A resposta mostra o servidor fora de transação: a query não rodou na de outra execução.
+                    if (!foreign || (err !== undefined && err !== null) || analysis.transaction.length > 0)
+                        return;
+                    if (serverTransactionStatus(client, state.observedStatus) !== 'I')
+                        return;
+                    delete span.attributes.links;
+                    delete span.attributes['db.transaction.foreign'];
+                },
+            });
         };
     };
     /** Envolve o `release` desta retirada (o pool troca a função a cada `connect`). */
@@ -450,7 +699,7 @@ export function instrumentPgPool(core, pool) {
             return;
         client.release = function fgTrackerRelease(...args) {
             state.internal = false;
-            if (state.tx)
+            if (state.tx || state.queued)
                 endTransaction(state, 'released_open', args[0] instanceof Error ? args[0] : undefined);
             client.release = release;
             return Reflect.apply(release, this, args);
@@ -471,8 +720,10 @@ export function instrumentPgPool(core, pool) {
         try {
             if (!tracked)
                 return original(...args);
-            return runQuery(core, original, args, sql, baseAttributes, undefined, (span) => {
-                marker.span = span;
+            return runQuery(core, original, args, sql, baseAttributes, {
+                onStart: (span) => {
+                    marker.span = span;
+                },
             });
         }
         finally {