velocious 1.0.602 → 1.0.604

package/README.md

@@ -26,6 +26,7 @@
 * Gap-less positional lists with automatic reordering via `actsAsList`, including models with numeric, string, or UUID primary keys (see [docs/acts-as-list.md](docs/acts-as-list.md))
 * Rails-style nested-attribute writes on frontend-model `save()` (see [docs/nested-attributes.md](docs/nested-attributes.md))
 * Async-aware test-data factories with inherited traits, graph-first native association autosave, metadata-aware override precedence, callbacks, sequences, linting, and a process-global reload-retention budget that bounds cache-busted re-import memory (see [docs/factories.md](docs/factories.md))
+* Opt-in Benchmark-style test profiling with privacy-safe rich JSON and directly reusable duration-aware shard manifests (see [docs/test-profiling.md](docs/test-profiling.md))
 * Per-row association counts via `.withCount(...)`, including cohort-safe intersected filters, safe batching of structurally identical aggregates, and automatic IN-list chunking for large parent sets, on frontend and backend queries (see [docs/with-count.md](docs/with-count.md))
 * Consumer-defined per-row SQL aggregates/computations via `.queryData(...)`, with compatible projections sharing a roundtrip while preserving declared alias-overwrite order and automatic IN-list chunking for large parent sets, on frontend and backend queries (see [docs/query-data.md](docs/query-data.md))
 * Per-record ability checks via `.abilities(...)` on frontend queries + `record.can(action)` (see [docs/abilities.md](docs/abilities.md))
@@ -227,6 +228,22 @@ Slowest 10 tests:
 
 The report is skipped for single-test runs. See [docs/testing-guidelines.md](docs/testing-guidelines.md).
 
+Add `--profile` for a compact Benchmark-style phase and pool summary. Use
+`--profile-json <path>` for versioned, privacy-safe detail or
+`--timing-manifest-output <path>` to generate a sorted per-file duration map for
+the existing `--timing-manifest` shard input; either output flag implies
+profiling.
+
+```bash
+npx velocious test --profile-json tmp/test-profile.json \
+  --timing-manifest-output tmp/test-timings.json
+npx velocious test --groups=4 --group-number=1 \
+  --timing-manifest tmp/test-timings.json
+```
+
+See [test profiling](docs/test-profiling.md) for lifecycle accounting, custom
+activity spans, schema, and privacy guarantees.
+
 Prefer waiting for a real signal or condition over sleeping a fixed duration. `waitForEvent(emitter, eventName, {timeoutMs, filter})` resolves the instant a matching event fires (a background job finishing, a model update, a websocket message) and rejects on timeout; for polling an arbitrary condition, use awaitery's `waitFor`.
 
 ```js
@@ -1769,7 +1786,12 @@ database: {
 
 `pool.max` caps live async-tracked connections for that pool and defaults to `10` when omitted. When the cap is reached, new checkouts wait until a matching checked-in connection can be handed over or capacity is freed. Set `pool.max` to `null` only when a process is deliberately allowed to open an unbounded number of database connections. The built-in debug endpoint reports each in-use connection's `checkedOutForMs`, each idle connection's `idleForMs`, and queued `pendingCheckouts[].waitingForMs` so production diagnostics can distinguish long-held checkouts from pool-capacity waits.
 
-Debug snapshots also expose cumulative checkout-wait and idle-reaper disposal telemetry. The [MySQL idle-reaping benchmark and methodology](docs/mysql-pool-idle-reaping-research.md) compare the 5-second default with 60 seconds and disabled reaping under a fixed cap; absent representative measured evidence, retain the 5-second default.
+Debug snapshots also expose cumulative connection-creation, checkout-wait and
+timeout, idle-reap, and peak-live-connection telemetry. Opt-in test profiles can
+attribute safe aggregate deltas to their current spans. The [MySQL idle-reaping
+benchmark and methodology](docs/mysql-pool-idle-reaping-research.md) compare the
+5-second default with 60 seconds and disabled reaping under a fixed cap; absent
+representative measured evidence, retain the 5-second default.
 
 # Websockets
 
@@ -1921,10 +1943,21 @@ Genuinely unexpected frontend-model command failures reach this bus too. The fro
 
 Unexpected inbound decoded WebSocket dispatch failures emit one `framework-error` and one matching `all-error`. Established expected client-flow errors remain excluded from both events.
 
-MySQL/MariaDB transaction deadlock retries emit a structured `database-deadlock-retry` event (also
-mirrored to `all-error`) with retry metadata, a redacted SQL fingerprint when available, and a
-best-effort bounded/redacted InnoDB deadlock excerpt. Diagnostic capture never joins the retry
-control flow. See [deadlock retry diagnostics](docs/logging.md#deadlock-retry-diagnostics).
+MySQL/MariaDB transaction contention that will run another outer attempt emits a structured
+`database-deadlock-retry` event through `configuration.getErrorEvents()` and mirrors it to `all-error` with
+`errorType: "database-deadlock-retry"`. Required context fields are `stage`, `driverType`,
+`contentionKind`, `attempt`, `maxAttempts`, `willRetry` (always `true` for this retry-only event), and
+`transactionAttemptDurationMs`. Exhausted/non-retried contention emits no retry event.
+Pool-owned connections optionally add logical `databaseIdentifier` and opaque
+`databaseIdentifierFingerprint`/`databaseIdentityFingerprint` fields; the logical identifier itself
+is always redacted. Named checkouts always redact `operationName` and add only its bounded opaque
+`operationNameFingerprint` for correlation. Query failures add
+`sqlOperation`/`sqlFingerprint`. True deadlocks may add `statusCapture` and the bounded structural
+`innodbDeadlockSummary`, including explicit bounded MariaDB counterparty conflict edges whose owner
+is intentionally not inferred; lock-wait timeouts report `statusCapture: "not-applicable"` and never attach a
+historical graph. Capture, parsing, and listeners remain detached from rollback and retry control
+flow. See the exact identity, redaction, structural bounds, failure-channel, and optional-field
+contract in [deadlock retry diagnostics](docs/logging.md#deadlock-retry-diagnostics).
 
 ## Use the Websocket client API (HTTP-like)
 

package/build/configuration.js

@@ -35,6 +35,7 @@ import {frontendModelApiManifest, frontendModelResourceClassFromDefinition, fron
 import {currentOfflineGrantSigningKey, normalizeOfflineGrantSigningKey} from "./sync/offline-grant.js"
 import PluginRoutes from "./routes/plugin-routes.js"
 import restArgsError from "./utils/rest-args-error.js"
+import { validateTestActivityName } from "./testing/test-profile-activity.js"
 import {validateTimeZone} from "./time-zone.js"
 import {withTrackedStack} from "./utils/with-tracked-stack.js"
 import VelociousPackage from "./packages/velocious-package.js"
@@ -3150,6 +3151,24 @@ export default class VelociousConfiguration {
     return await this.getEnvironmentHandler().runWithRequestTiming(requestTiming, callback)
   }
 
+  /**
+   * Profiles an application-defined test activity when an opt-in test profile
+   * context is active. The callback always runs, including outside profiling.
+   * @template T
+   * @param {string} name - Low-cardinality activity identifier.
+   * @param {() => (T | Promise<T>)} callback - Activity callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async profileTestActivity(name, callback) {
+    const validatedName = validateTestActivityName(name)
+
+    const context = this.getEnvironmentHandler().getCurrentTestProfileContext()
+
+    if (!context) return await callback()
+
+    return await context.profiler.profileActivity(context, validatedName, callback)
+  }
+
   /**
    * Runs run with timezone.
    * @param {string} timeZone - IANA timezone identifier.

package/build/database/drivers/base.js

@@ -54,6 +54,7 @@
  * @property {boolean} retry - Whether the error should be retried.
  * @property {boolean} reconnect - Whether to reconnect before retrying.
  * @property {boolean} [deadlock] - Whether the error is a transaction deadlock/lock-wait-timeout that should retry the whole transaction.
+ * @property {"deadlock" | "lock-wait-timeout"} [contentionKind] - Classified transaction contention kind.
  * @property {number} [maxTries] - Override the max retry attempts.
  * @property {number} [waitMs] - Wait time before retrying in milliseconds.
  */
@@ -71,6 +72,33 @@
  * @property {symbol} [operationOwner] - Opaque owner for an operation-leased connection.
  */
 
+/**
+ * DeadlockRetryDiagnosticSnapshot type.
+ * @typedef {object} DeadlockRetryDiagnosticSnapshot
+ * @property {number} attempt - One-based transaction attempt.
+ * @property {"deadlock" | "lock-wait-timeout"} contentionKind - Classified contention kind.
+ * @property {string} [databaseIdentifier] - Redacted logical database pool identifier marker.
+ * @property {string} [databaseIdentifierFingerprint] - Opaque logical database pool identity.
+ * @property {string} [databaseIdentityFingerprint] - Opaque physical database identity.
+ * @property {string} driverType - Driver type.
+ * @property {number} maxAttempts - Configured transaction attempt budget.
+ * @property {string} [operationName] - Redacted operation-name marker.
+ * @property {string} [operationNameFingerprint] - Opaque operation-name identity.
+ * @property {string} [sqlFingerprint] - Normalized SQL-shape fingerprint.
+ * @property {string} [sqlOperation] - SQL verb.
+ * @property {string} stage - Error-event stage.
+ * @property {number} transactionAttemptDurationMs - Duration of the failed outer attempt.
+ * @property {boolean} willRetry - Whether another outer transaction attempt will run.
+ */
+
+/**
+ * TestProfileQueryAttempt type.
+ * @typedef {object} TestProfileQueryAttempt
+ * @property {import("../../testing/test-profiler.js").TestProfileAsyncContext} context - Captured async attribution.
+ * @property {{sqlFingerprint: string, sqlOperation: string}} diagnostic - Redacted statement diagnostic.
+ * @property {number} startedAtMs - Physical attempt start time.
+ */
+
 /**
  * ActiveQueryDebugSnapshot type.
  * @typedef {object} ActiveQueryDebugSnapshot
@@ -144,19 +172,24 @@ import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/build/wait.js"
 import { optionalPositiveInteger } from "typanic"
 import { coordinateSharedTransactionConnection } from "../../testing/shared-transaction-connection-coordinator.js"
+import { currentTestProfileContext } from "../../testing/test-profile-context.js"
+import sha256Hex from "../../utils/sha256-hex.js"
 
 /** Maximum characters inspected when building the debug SQL preview. */
 const SQL_PREVIEW_SCAN_LIMIT = 4096
 /** Maximum characters inspected when deciding whether a statement invalidates schema metadata. */
 const SCHEMA_INVALIDATION_SCAN_LIMIT = 8192
+/** Maximum checkout-name characters inspected by retry diagnostics. */
+const OPERATION_NAME_SCAN_LIMIT = 1024
+const REDACTED_DIAGNOSTIC_LABEL = "[REDACTED]"
 
 /**
  * Builds a non-reversible, stable SQL fingerprint without retaining SQL text. Literal spelling is
  * normalized first so the same statement shape produces the same fingerprint across values.
  * @param {string} sql - SQL to fingerprint.
- * @returns {string} - Bounded fingerprint.
+ * @returns {{sqlFingerprint: string, sqlOperation: string}} - Bounded query diagnostic.
  */
-function sqlFingerprint(sql) {
+function sqlDiagnostic(sql) {
   let fingerprintInput = ""
 
   for (let index = 0; index < sql.length;) {
@@ -206,7 +239,12 @@ function sqlFingerprint(sql) {
     hash = BigInt.asUintN(64, hash * 0x100000001b3n)
   }
 
-  return `fnv1a64:${hash.toString(16).padStart(16, "0")}`
+  const operationMatch = /^([a-z]+)/.exec(normalized)
+
+  return {
+    sqlFingerprint: `fnv1a64:${hash.toString(16).padStart(16, "0")}`,
+    sqlOperation: operationMatch ? operationMatch[1].toUpperCase() : "UNKNOWN"
+  }
 }
 
 /**
@@ -270,6 +308,10 @@ export default class VelociousDatabaseDriversBase {
    * Narrows the runtime value to the documented type.
    * @type {string | undefined} */
   _connectionCheckoutName
+  /** @type {string | undefined} */
+  _databaseIdentifier
+  /** @type {string | undefined} */
+  _databaseIdentityFingerprint
   /**
    * Active query.
    * @type {ActiveQueryState | null} */
@@ -465,6 +507,16 @@ export default class VelociousDatabaseDriversBase {
     this._connectionCheckedOutAtUnixMs = undefined
   }
 
+  /**
+   * Sets the pool-owned identity used by safe database diagnostics.
+   * @param {{databaseIdentifier: string, databaseIdentityFingerprint: string}} identity - Pool-stamped identity redacted at diagnostic snapshot time.
+   * @returns {void}
+   */
+  setPoolDiagnosticIdentity({databaseIdentifier, databaseIdentityFingerprint}) {
+    this._databaseIdentifier = databaseIdentifier
+    this._databaseIdentityFingerprint = databaseIdentityFingerprint
+  }
+
   /**
    * Runs reconnect.
    * @returns {Promise<void>} - Resolves when complete.
@@ -1304,6 +1356,7 @@ export default class VelociousDatabaseDriversBase {
 
     while (true) {
       attempt++
+      const attemptStartedAtMs = this._nowMs()
 
       try {
         return await this._runTransactionAttempt(callback, options)
@@ -1312,9 +1365,17 @@ export default class VelociousDatabaseDriversBase {
         if (!(error instanceof Error)) throw error
 
         const retryInfo = this.retryableDatabaseError(error)
-
-        if (retryInfo.deadlock && attempt < maxAttempts && this._transactionsCount == 0) {
-          this._reportDeadlockRetryDiagnostic({attempt, error, maxAttempts})
+        const willRetry = Boolean(retryInfo.deadlock && attempt < maxAttempts && this._transactionsCount == 0)
+
+        if (willRetry) {
+          this._reportDeadlockRetryDiagnostic({
+            attempt,
+            contentionKind: retryInfo.contentionKind || "deadlock",
+            error,
+            maxAttempts,
+            transactionAttemptDurationMs: Math.max(0, this._nowMs() - attemptStartedAtMs),
+            willRetry
+          })
 
           // An explicitly-configured base wins so the tuning knob is effective even on drivers
           // whose classifier supplies its own `waitMs` (MySQL/MariaDB return a fixed 50ms for
@@ -1330,7 +1391,9 @@ export default class VelociousDatabaseDriversBase {
           const ceilingWaitMs = Math.min(baseWaitMs * (2 ** (attempt - 1)), deadlockMaxWaitMs)
           const jitteredWaitMs = Math.floor(Math.random() * (ceilingWaitMs + 1))
 
-          this.logger.warn(`Retrying transaction after deadlock (attempt ${attempt}/${maxAttempts})`)
+          const loggedContentionKind = retryInfo.contentionKind || "transaction contention"
+
+          this.logger.warn(`Retrying transaction after ${loggedContentionKind} (attempt ${attempt}/${maxAttempts})`)
           await this._waitMs(jitteredWaitMs)
           continue
         }
@@ -1350,29 +1413,67 @@ export default class VelociousDatabaseDriversBase {
     await wait(ms)
   }
 
+  /**
+   * Returns the clock used for transaction-attempt diagnostics.
+   * @returns {number} - Monotonic milliseconds where available.
+   */
+  _nowMs() {
+    return nowMs()
+  }
+
   /**
    * Starts best-effort deadlock diagnostics without joining the retry control flow. Subclasses may
    * add bounded driver-specific context; capture and event-listener failures cannot affect retry.
-   * @param {{attempt: number, error: Error, maxAttempts: number}} args - Retry metadata.
+   * @param {{attempt: number, contentionKind: "deadlock" | "lock-wait-timeout", error: Error, maxAttempts: number, transactionAttemptDurationMs: number, willRetry: boolean}} args - Retry metadata.
    * @returns {void}
    */
-  _reportDeadlockRetryDiagnostic({attempt, error, maxAttempts}) {
-    const queryDiagnostic = this._failedQueryDiagnostics.get(error)
+  _reportDeadlockRetryDiagnostic({attempt, contentionKind, error, maxAttempts, transactionAttemptDurationMs, willRetry}) {
+    let snapshot
+
+    try {
+      const queryDiagnostic = this._failedQueryDiagnostics.get(error)
+
+      snapshot = Object.freeze({
+        attempt,
+        contentionKind,
+        driverType: this.getType(),
+        maxAttempts,
+        stage: "database-deadlock-retry",
+        transactionAttemptDurationMs,
+        willRetry,
+        ...this._poolDiagnosticIdentityContext(),
+        ...this._operationDiagnosticContext(),
+        ...queryDiagnostic
+      })
+    } catch (diagnosticError) {
+      this._reportDeadlockDiagnosticPipelineFailure(diagnosticError)
+      return
+    }
+
+    let driverContextResult
+
+    try {
+      driverContextResult = this._deadlockDiagnosticContext(snapshot)
+    } catch (diagnosticError) {
+      this._reportDeadlockDiagnosticPipelineFailure(diagnosticError)
+      return
+    }
 
-    void this._deadlockDiagnosticContext()
+    const hasPromiseContract = driverContextResult instanceof Promise
+
+    void Promise.resolve(driverContextResult)
       .then((driverContext) => {
+        if (!hasPromiseContract) throw new Error("Database deadlock diagnostic context must return a Promise")
+
         const context = {
-          attempt,
-          driverType: this.getType(),
-          maxAttempts,
-          stage: "database-deadlock-retry",
-          willRetry: true,
-          ...queryDiagnostic,
+          ...snapshot,
           ...driverContext
         }
         const payload = {
           context,
-          error: new Error("Database transaction deadlock will be retried")
+          error: new Error(willRetry
+            ? `Database transaction ${contentionKind} will be retried`
+            : `Database transaction ${contentionKind} exhausted its retry budget`)
         }
         const errorEvents = this.configuration.getErrorEvents()
 
@@ -1388,30 +1489,93 @@ export default class VelociousDatabaseDriversBase {
           this.logger.warn("Database deadlock retry all-error listener failed", {error: eventError})
         }
       })
-      .catch((diagnosticError) => {
-        const normalizedError = diagnosticError instanceof Error
-          ? diagnosticError
-          : new Error("Database deadlock retry diagnostic failed", {cause: diagnosticError})
-        const payload = {
-          context: {stage: "database-deadlock-retry-diagnostic"},
-          error: normalizedError
-        }
+      .catch((diagnosticError) => this._reportDeadlockDiagnosticPipelineFailure(diagnosticError))
+  }
 
-        try {
-          const errorEvents = this.configuration.getErrorEvents()
-          errorEvents.emit("framework-error", payload)
-          errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
-        } catch (reportingError) {
-          this.logger.warn("Database deadlock retry diagnostic pipeline failed", {error: normalizedError, reportingError})
-        }
-      })
+  /**
+   * Returns pool identity only when this driver was stamped by a pool.
+   * @returns {{databaseIdentifier?: string, databaseIdentifierFingerprint?: string, databaseIdentityFingerprint?: string}} - Safe pool identity.
+   */
+  _poolDiagnosticIdentityContext() {
+    if (this._databaseIdentifier === undefined || !this._databaseIdentityFingerprint) return {}
+
+    const identifierFingerprintInput = typeof this._databaseIdentifier === "string"
+      ? this._databaseIdentifier
+      : `invalid:${typeof this._databaseIdentifier}`
+    const databaseIdentifierFingerprint = `sha256:${sha256Hex(`database-logical-identifier:v1\0${identifierFingerprintInput}`)}`
+
+    return {
+      databaseIdentifier: REDACTED_DIAGNOSTIC_LABEL,
+      databaseIdentifierFingerprint,
+      databaseIdentityFingerprint: this._databaseIdentityFingerprint
+    }
+  }
+
+  /**
+   * Builds the bounded operation portion of an immutable retry snapshot.
+   * @returns {{operationName?: string, operationNameFingerprint?: string}} - Safe operation fields.
+   */
+  _operationDiagnosticContext() {
+    const rawOperationName = this._connectionCheckoutName
+
+    if (rawOperationName === undefined) return {}
+    if (typeof rawOperationName !== "string") {
+      return {
+        operationName: REDACTED_DIAGNOSTIC_LABEL,
+        operationNameFingerprint: `sha256:${sha256Hex(`database-operation:v1\0invalid:${typeof rawOperationName}`)}`
+      }
+    }
+
+    const scannedOperationName = rawOperationName.slice(0, OPERATION_NAME_SCAN_LIMIT)
+    const operationNameFingerprint = `sha256:${sha256Hex(`database-operation:v1\0${scannedOperationName}\0length:${rawOperationName.length}`)}`
+
+    return {
+      operationName: REDACTED_DIAGNOSTIC_LABEL,
+      operationNameFingerprint
+    }
+  }
+
+  /**
+   * Reports an unexpected detached diagnostics failure without changing transaction control flow.
+   * @param {ReturnType<typeof JSON.parse>} diagnosticError - Diagnostics failure.
+   * @returns {void}
+   */
+  _reportDeadlockDiagnosticPipelineFailure(diagnosticError) {
+    const normalizedError = diagnosticError instanceof Error
+      ? diagnosticError
+      : new Error("Database deadlock retry diagnostic failed", {cause: diagnosticError})
+    const payload = {
+      context: {stage: "database-deadlock-retry-diagnostic"},
+      error: normalizedError
+    }
+    let errorEvents
+
+    try {
+      errorEvents = this.configuration.getErrorEvents()
+    } catch (reportingError) {
+      this.logger.warn("Database deadlock retry diagnostic pipeline reporting failed", {error: normalizedError, reportingError})
+      return
+    }
+
+    try {
+      errorEvents.emit("framework-error", payload)
+    } catch (reportingError) {
+      this.logger.warn("Database deadlock retry framework-error listener failed", {error: normalizedError, reportingError})
+    }
+
+    try {
+      errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+    } catch (reportingError) {
+      this.logger.warn("Database deadlock retry all-error listener failed", {error: normalizedError, reportingError})
+    }
   }
 
   /**
    * Builds driver-specific deadlock context. The base driver has no server diagnostic source.
+   * @param {DeadlockRetryDiagnosticSnapshot} _snapshot - Immutable retry snapshot.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - Safe context fields.
    */
-  async _deadlockDiagnosticContext() {
+  async _deadlockDiagnosticContext(_snapshot) {
     return {}
   }
 
@@ -1585,7 +1749,9 @@ export default class VelociousDatabaseDriversBase {
           return
         }
 
-        await this._startTransactionAction(options)
+        await this._runProfiledTransactionAction("start", async () => {
+          await this._startTransactionAction(options)
+        })
         this._transactionsCount++
 
         if (this._transactionsCount === 1) {
@@ -1617,7 +1783,9 @@ export default class VelociousDatabaseDriversBase {
    */
   async commitTransaction(options = {}) {
     await this._transactionsActionsMutex.sync(async () => {
-      await this._commitTransactionAction(options)
+      await this._runProfiledTransactionAction("commit", async () => {
+        await this._commitTransactionAction(options)
+      })
       this._transactionsCount--
       this._resolveCompletedTransaction()
     })
@@ -1642,6 +1810,68 @@ export default class VelociousDatabaseDriversBase {
     await this.query("COMMIT", options)
   }
 
+  /**
+   * Times a physical transaction action only when test profiling is active.
+   * @template T
+   * @param {"start" | "commit" | "rollback"} action - Transaction action.
+   * @param {() => Promise<T>} callback - Physical action callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async _runProfiledTransactionAction(action, callback) {
+    const profileContext = currentTestProfileContext(this.configuration)
+
+    if (!profileContext) return await callback()
+
+    const startedAtMs = nowMs()
+    let failed = true
+
+    try {
+      const result = await callback()
+
+      failed = false
+      return result
+    } finally {
+      profileContext.profiler.recordDatabaseTransaction(profileContext, {
+        action,
+        durationMs: nowMs() - startedAtMs,
+        failed
+      })
+    }
+  }
+
+  /**
+   * Starts an optional physical-query profile attempt without retaining SQL.
+   * @param {string} sql - Original SQL used only to derive its redacted diagnostic.
+   * @returns {TestProfileQueryAttempt | undefined} - Active profile handle.
+   */
+  _startProfiledQueryAttempt(sql) {
+    const context = currentTestProfileContext(this.configuration)
+
+    if (!context) return undefined
+
+    return {
+      context,
+      diagnostic: sqlDiagnostic(sql),
+      startedAtMs: nowMs()
+    }
+  }
+
+  /**
+   * Completes an optional physical-query profile attempt.
+   * @param {TestProfileQueryAttempt | undefined} attempt - Profile handle.
+   * @param {boolean} failed - Whether the physical driver call failed.
+   * @returns {void}
+   */
+  _finishProfiledQueryAttempt(attempt, failed) {
+    if (!attempt) return
+
+    attempt.context.profiler.recordDatabaseQuery(attempt.context, {
+      durationMs: nowMs() - attempt.startedAtMs,
+      failed,
+      ...attempt.diagnostic
+    })
+  }
+
   /**
    * Runs every guard registered to the transaction frame.
    * @param {TransactionCallbackFrame} callbackFrame - Frame whose guards are completing.
@@ -1716,10 +1946,7 @@ export default class VelociousDatabaseDriversBase {
       } catch (error) {
         if (!(error instanceof Error)) throw error
 
-        this._failedQueryDiagnostics.set(error, {
-          sqlFingerprint: sqlFingerprint(sql),
-          sqlOperation: sql.trim().split(/\s+/, 1)[0]?.toUpperCase() || "UNKNOWN"
-        })
+        this._failedQueryDiagnostics.set(error, sqlDiagnostic(sql))
 
         // A deliberately-aborted query must never be silently re-run — its
         // connection was destroyed on purpose, so treat it as terminal.
@@ -1764,7 +1991,17 @@ export default class VelociousDatabaseDriversBase {
       await this.beforeQuery(sql, options)
 
       try {
-        return await this._affectedRowsActual(sql)
+        const profileAttempt = this._startProfiledQueryAttempt(sql)
+        let failed = true
+
+        try {
+          const affectedRows = await this._affectedRowsActual(sql)
+
+          failed = false
+          return affectedRows
+        } finally {
+          this._finishProfiledQueryAttempt(profileAttempt, failed)
+        }
       } finally {
         await this.afterQuery(sql, options)
       }
@@ -1793,7 +2030,7 @@ export default class VelociousDatabaseDriversBase {
     let result
 
     try {
-      const runQueryActualWithHooks = async () => await this._queryActualWithHooks(querySql, options)
+      const runQueryActualWithHooks = async () => await this._queryActualWithHooks(querySql, options, originalSql)
 
       if (requestTiming && tries === 1) {
         result = await requestTiming.measureDbQuery(runQueryActualWithHooks)
@@ -1828,14 +2065,25 @@ export default class VelociousDatabaseDriversBase {
    * Runs query actual with before/after hooks.
    * @param {string} sql - SQL string.
    * @param {QueryOptions} options - Query options.
+   * @param {string} originalSql - SQL before process-list comments.
    * @returns {Promise<QueryResultType>} - Resolves with the query.
    */
-  async _queryActualWithHooks(sql, options) {
+  async _queryActualWithHooks(sql, options, originalSql) {
     return await coordinateSharedTransactionConnection(this, async () => {
       await this.beforeQuery(sql, options)
 
       try {
-        return await this._queryActual(sql, options)
+        const profileAttempt = this._startProfiledQueryAttempt(originalSql)
+        let failed = true
+
+        try {
+          const result = await this._queryActual(sql, options)
+
+          failed = false
+          return result
+        } finally {
+          this._finishProfiledQueryAttempt(profileAttempt, failed)
+        }
       } finally {
         await this.afterQuery(sql, options)
       }
@@ -2251,7 +2499,9 @@ export default class VelociousDatabaseDriversBase {
   async rollbackTransaction(options = {}) {
     await this._transactionsActionsMutex.sync(async () => {
       try {
-        await this._rollbackTransactionAction(options)
+        await this._runProfiledTransactionAction("rollback", async () => {
+          await this._rollbackTransactionAction(options)
+        })
       } finally {
         this._transactionsCount--
         this._resolveCompletedTransaction()