velocious 1.0.603 → 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
 

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

@@ -91,6 +91,14 @@
  * @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
@@ -164,6 +172,7 @@ 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. */
@@ -1740,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) {
@@ -1772,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()
     })
@@ -1797,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.
@@ -1916,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)
       }
@@ -1945,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)
@@ -1980,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)
       }
@@ -2403,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()

package/build/database/drivers/mysql/index.js

@@ -518,7 +518,15 @@ export default class VelociousDatabaseDriversMysql extends Base{
     if (!this.pool) await this.connect()
     if (!this.pool) throw new Error("MySQL pool failed to initialize")
 
-    yield* streamQuery(this.pool, sql)
+    const profileAttempt = this._startProfiledQueryAttempt(sql)
+    let failed = true
+
+    try {
+      yield* streamQuery(this.pool, sql)
+      failed = false
+    } finally {
+      this._finishProfiledQueryAttempt(profileAttempt, failed)
+    }
   }
 
   /**
@@ -558,13 +566,20 @@ export default class VelociousDatabaseDriversMysql extends Base{
     if (!this.pool) throw new Error("MySQL pool failed to initialize")
 
     const pool = this.pool
+    const profileAttempt = this._startProfiledQueryAttempt(structureSql)
+    let failed = true
 
-    await new Promise((resolve, reject) => {
-      pool.query(structureSql, (error) => {
-        if (error) reject(error)
-        else resolve(undefined)
+    try {
+      await new Promise((resolve, reject) => {
+        pool.query(structureSql, (error) => {
+          if (error) reject(error)
+          else resolve(undefined)
+        })
       })
-    })
+      failed = false
+    } finally {
+      this._finishProfiledQueryAttempt(profileAttempt, failed)
+    }
 
     return true
   }

package/build/database/pool/async-tracked-multi-connection.js

@@ -1,7 +1,8 @@
 // @ts-check
 
-import {AsyncLocalStorage} from "async_hooks"
-import BasePool, {POOL_CONFIGURATION_KEY} from "./base.js"
+import { AsyncLocalStorage } from "async_hooks"
+import BasePool, { POOL_CONFIGURATION_KEY } from "./base.js"
+import { currentTestProfileContext } from "../../testing/test-profile-context.js"
 
 /**
  * PendingCheckout type.
@@ -15,6 +16,7 @@ import BasePool, {POOL_CONFIGURATION_KEY} from "./base.js"
  * @property {number | null} timeoutAt - Timestamp when the checkout will time out, or null when disabled.
  * @property {number | null} timeoutMillis - Milliseconds to wait before rejecting, or null when disabled.
  * @property {ReturnType<typeof setTimeout> | undefined} timeoutTimer - Timer that rejects the pending checkout.
+ * @property {import("../../testing/test-profiler.js").TestProfileAsyncContext | undefined} [testProfileContext] - Async-safe profile attribution captured at enqueue.
  */
 export const CLOSED_CONNECTION = Symbol("velociousClosedConnection")
 const IDLE_CONNECTION_CHECKED_IN_AT = Symbol("velociousIdleConnectionCheckedInAt")
@@ -115,10 +117,20 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /** Cumulative low-cardinality pool telemetry. */
   telemetry = {
+    connectionCreationCount: 0,
+    connectionCreationFailureCount: 0,
+    connectionCreationMaxMs: 0,
+    connectionCreationTotalMs: 0,
+    checkoutTimeoutCount: 0,
     checkoutWaitCount: 0,
     checkoutWaitMaxMs: 0,
     checkoutWaitTotalMs: 0,
-    idleReapDisposalCount: 0
+    idleReapCount: 0,
+    idleReapDisposalCount: 0,
+    idleReapFailureCount: 0,
+    idleReapMaxMs: 0,
+    idleReapTotalMs: 0,
+    peakLiveConnections: 0
   }
 
   idSeq = 0
@@ -139,6 +151,58 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     this._withoutCurrentConnectionContext = withoutCurrentConnectionContext
   }
 
+  /**
+   * Returns the pool telemetry clock.
+   * @returns {number} - Current time in milliseconds.
+   */
+  nowMs() { return Date.now() }
+
+  /**
+   * Records a pool metric in the active async-safe test profile context.
+   * @param {import("../../testing/test-profiler.js").TestProfileAsyncContext | undefined} context - Captured profile context.
+   * @param {"connectionCreation" | "checkoutWait" | "checkoutTimeout" | "idleReap" | "idleReapDisposal" | "peakLiveConnections"} metric - Metric name.
+   * @param {{durationMs?: number, failed?: boolean, value?: number}} [values] - Aggregate values.
+   * @returns {void}
+   */
+  recordTestProfilePoolMetric(context, metric, values = {}) {
+    if (!context) return
+
+    context.profiler.recordPoolMetric(context, this.identifier, metric, values)
+  }
+
+  /**
+   * Spawns and times a physical connection without retaining its configuration.
+   * @param {import("../../configuration-types.js").DatabaseConfigurationType} config - Resolved database configuration.
+   * @returns {Promise<import("../drivers/base.js").default>} - Connected driver.
+   */
+  async spawnConnectionWithConfiguration(config) {
+    const startedAt = this.nowMs()
+    const profileContext = currentTestProfileContext(this.configuration)
+    let failed = true
+
+    try {
+      const connection = await super.spawnConnectionWithConfiguration(config)
+
+      failed = false
+      const liveConnectionCount = this.liveConnectionCount() - this.connectionsBeingSpawned + 1
+
+      if (liveConnectionCount > this.telemetry.peakLiveConnections) {
+        this.telemetry.peakLiveConnections = liveConnectionCount
+        this.recordTestProfilePoolMetric(profileContext, "peakLiveConnections", {value: liveConnectionCount})
+      }
+
+      return connection
+    } finally {
+      const durationMs = Math.max(0, this.nowMs() - startedAt)
+
+      this.telemetry.connectionCreationCount++
+      if (failed) this.telemetry.connectionCreationFailureCount++
+      this.telemetry.connectionCreationTotalMs += durationMs
+      this.telemetry.connectionCreationMaxMs = Math.max(this.telemetry.connectionCreationMaxMs, durationMs)
+      this.recordTestProfilePoolMetric(profileContext, "connectionCreation", {durationMs, failed})
+    }
+  }
+
   /**
    * Runs checkin.
    * @param {import("../drivers/base.js").default} connection - Database connection instance.
@@ -258,7 +322,11 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
       // The post-reap configuration is fresh for the current caller, and its reuse key is
       // derived from this exact captured object so the connection cannot open one tenant while
       // being stamped for another. The queued path retains the same captured pair.
-      connection = await this.spawnConnectionForCheckout(databaseConfig, reuseKey)
+      connection = await this.spawnConnectionForCheckout(
+        databaseConfig,
+        reuseKey,
+        currentTestProfileContext(this.configuration)
+      )
 
       return await this.activateConnection(connection, options)
     }
@@ -291,7 +359,11 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     if (connection) return await this.activateConnection(connection, options)
 
     if (this.canSpawnConnection(databaseConfig)) {
-      connection = await this.spawnConnectionForCheckout(databaseConfig, reuseKey)
+      connection = await this.spawnConnectionForCheckout(
+        databaseConfig,
+        reuseKey,
+        currentTestProfileContext(this.configuration)
+      )
 
       return await this.activateConnection(connection, options)
     }
@@ -436,13 +508,17 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * Runs spawn connection for checkout.
    * @param {import("../../configuration-types.js").DatabaseConfigurationType} databaseConfig - Resolved database config for the checkout.
    * @param {string} reuseKey - Database configuration reuse key for the checkout.
+   * @param {import("../../testing/test-profiler.js").TestProfileAsyncContext | undefined} profileContext - Profile context captured when checkout began.
    * @returns {Promise<import("../drivers/base.js").default>} - Spawned connection.
    */
-  async spawnConnectionForCheckout(databaseConfig, reuseKey) {
+  async spawnConnectionForCheckout(databaseConfig, reuseKey, profileContext) {
     this.connectionsBeingSpawned++
 
     try {
-      const connection = await this.spawnConnectionWithConfiguration(databaseConfig)
+      const environmentHandler = this.configuration.getEnvironmentHandler()
+      const connection = await environmentHandler.runWithTestProfileContext(profileContext, async () => {
+        return await this.spawnConnectionWithConfiguration(databaseConfig)
+      })
 
       this.stampConnectionForConfigurationReuseKey(connection, reuseKey)
 
@@ -473,7 +549,8 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
         reuseKey,
         timeoutAt: timeoutMillis === null ? null : enqueuedAt + timeoutMillis,
         timeoutMillis,
-        timeoutTimer: undefined
+        timeoutTimer: undefined,
+        testProfileContext: currentTestProfileContext(this.configuration)
       }
 
       checkout.timeoutTimer = this.startPendingCheckoutTimeout(checkout)
@@ -573,11 +650,12 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {void}
    */
   recordCheckoutWait(checkout) {
-    const waitedForMs = Math.max(0, Date.now() - checkout.enqueuedAt)
+    const waitedForMs = Math.max(0, this.nowMs() - checkout.enqueuedAt)
 
     this.telemetry.checkoutWaitCount++
     this.telemetry.checkoutWaitTotalMs += waitedForMs
     this.telemetry.checkoutWaitMaxMs = Math.max(this.telemetry.checkoutWaitMaxMs, waitedForMs)
+    this.recordTestProfilePoolMetric(checkout.testProfileContext, "checkoutWait", {durationMs: waitedForMs})
   }
 
   /**
@@ -606,6 +684,8 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     if (index === -1) return
 
     this.removePendingCheckoutAt(index)
+    this.telemetry.checkoutTimeoutCount++
+    this.recordTestProfilePoolMetric(checkout.testProfileContext, "checkoutTimeout")
     checkout.reject(this.pendingCheckoutTimeoutError(checkout))
   }
 
@@ -739,16 +819,24 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {Promise<void>} - Resolves when the checkout has been handled.
    */
   async spawnAndResolvePendingCheckout(checkout) {
-    let connection
+    const environmentHandler = this.configuration.getEnvironmentHandler()
 
-    try {
-      connection = await this.spawnConnectionForCheckout(checkout.databaseConfig, checkout.reuseKey)
-    } catch (error) {
-      checkout.reject(error instanceof Error ? error : new Error("Failed to spawn database connection.", {cause: error}))
-      return
-    }
+    return await environmentHandler.runWithTestProfileContext(checkout.testProfileContext, async () => {
+      let connection
+
+      try {
+        connection = await this.spawnConnectionForCheckout(
+          checkout.databaseConfig,
+          checkout.reuseKey,
+          checkout.testProfileContext
+        )
+      } catch (error) {
+        checkout.reject(error instanceof Error ? error : new Error("Failed to spawn database connection.", {cause: error}))
+        return
+      }
 
-    await this.resolvePendingCheckout(checkout, connection)
+      await this.resolvePendingCheckout(checkout, connection)
+    })
   }
 
   /**
@@ -758,11 +846,15 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {Promise<void>} - Resolves when the checkout has been handled.
    */
   async resolvePendingCheckout(checkout, connection) {
-    try {
-      checkout.resolve(await this.activateConnection(connection, checkout.options))
-    } catch (error) {
-      checkout.reject(error instanceof Error ? error : new Error("Failed to activate database connection.", {cause: error}))
-    }
+    const environmentHandler = this.configuration.getEnvironmentHandler()
+
+    return await environmentHandler.runWithTestProfileContext(checkout.testProfileContext, async () => {
+      try {
+        checkout.resolve(await this.activateConnection(connection, checkout.options))
+      } catch (error) {
+        checkout.reject(error instanceof Error ? error : new Error("Failed to activate database connection.", {cause: error}))
+      }
+    })
   }
 
   /**
@@ -1308,24 +1400,40 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     const idleTimeoutMillis = this.idleTimeoutMillis()
 
     if (idleTimeoutMillis === null) return
+    const startedAt = this.nowMs()
+    const profileContext = currentTestProfileContext(this.configuration)
+    let failed = true
+
+    try {
+      const {expiredConnections, keptConnections} = this.classifyIdleConnectionsForReaping({idleTimeoutMillis, now: this.nowMs()})
 
-    const {expiredConnections, keptConnections} = this.classifyIdleConnectionsForReaping({idleTimeoutMillis, now: Date.now()})
+      this.connections = keptConnections
+      await this.closeExpiredIdleConnections(expiredConnections, profileContext)
+      await this.awaitInflightConnectionCloses()
+      if (this.connections.length > 0) this.scheduleIdleConnectionReaper()
+      failed = false
+    } finally {
+      const durationMs = Math.max(0, this.nowMs() - startedAt)
 
-    this.connections = keptConnections
-    await this.closeExpiredIdleConnections(expiredConnections)
-    await this.awaitInflightConnectionCloses()
-    if (this.connections.length > 0) this.scheduleIdleConnectionReaper()
+      this.telemetry.idleReapCount++
+      if (failed) this.telemetry.idleReapFailureCount++
+      this.telemetry.idleReapTotalMs += durationMs
+      this.telemetry.idleReapMaxMs = Math.max(this.telemetry.idleReapMaxMs, durationMs)
+      this.recordTestProfilePoolMetric(profileContext, "idleReap", {durationMs, failed})
+    }
   }
 
   /**
    * Runs close expired idle connections.
    * @param {import("../drivers/base.js").default[]} expiredConnections - Connections to close.
+   * @param {import("../../testing/test-profiler.js").TestProfileAsyncContext | undefined} [profileContext] - Reaper profile context.
    * @returns {Promise<void>} - Resolves when closed.
    */
-  async closeExpiredIdleConnections(expiredConnections) {
+  async closeExpiredIdleConnections(expiredConnections, profileContext) {
     for (const connection of expiredConnections) {
       await this.closeConnection(connection)
       this.telemetry.idleReapDisposalCount++
+      this.recordTestProfilePoolMetric(profileContext, "idleReapDisposal")
     }
   }
 

package/build/database/pool/base.js

@@ -45,7 +45,7 @@ import sha256Hex from "../../utils/sha256-hex.js"
  * @property {Array<DatabasePoolPendingCheckoutDebugSnapshot>} [pendingCheckouts] - Waiting checkout snapshots.
  * @property {number} pendingCheckoutCount - Number of queued checkout requests.
  * @property {string} poolClass - Pool class name.
- * @property {{checkoutWaitCount: number, checkoutWaitMaxMs: number, checkoutWaitTotalMs: number, idleReapDisposalCount: number}} [telemetry] - Cumulative pool lifecycle telemetry.
+ * @property {{connectionCreationCount: number, connectionCreationFailureCount: number, connectionCreationMaxMs: number, connectionCreationTotalMs: number, checkoutTimeoutCount: number, checkoutWaitCount: number, checkoutWaitMaxMs: number, checkoutWaitTotalMs: number, idleReapCount: number, idleReapDisposalCount: number, idleReapFailureCount: number, idleReapMaxMs: number, idleReapTotalMs: number, peakLiveConnections: number}} [telemetry] - Cumulative pool lifecycle telemetry.
  */
 export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
 

package/build/environment-handlers/base.js

@@ -54,6 +54,22 @@ export default class VelociousEnvironmentHandlerBase {
    */
   runWithSharedTransactionCoordinatorOwner(_connection, _owner, callback) { return callback() }
 
+  /**
+   * Runs work with test-profile attribution. Runtimes without async-context
+   * storage execute the callback without installing ambient attribution.
+   * @template T
+   * @param {import("../testing/test-profiler.js").TestProfileAsyncContext | undefined} _context - Captured profile context, or an explicit absence of attribution.
+   * @param {() => T} callback - Profiled work.
+   * @returns {T} - Callback result.
+   */
+  runWithTestProfileContext(_context, callback) { return callback() }
+
+  /**
+   * Gets the current test-profile attribution context.
+   * @returns {import("../testing/test-profiler.js").TestProfileAsyncContext | undefined} - Active context.
+   */
+  getCurrentTestProfileContext() { return undefined }
+
   /**
    * Mutable ambient tenant used by runtimes without async-context storage.
    * @type {ReturnType<typeof JSON.parse> | undefined}